Errori e limiti di frequenza

Ogni endpoint fallisce allo stesso modo, quindi un client gestisce errori, limiti di frequenza e tentativi una volta sola e riutilizza quel codice ovunque, incluso su MCP.

Ogni risposta non-2xx è un oggetto JSON:

{
  "defined": false,
  "code": "TOO_MANY_REQUESTS",
  "message": "Too many requests",
  "data": { "reason": "rate_limit.exceeded", "retryAfterMs": 12000 }
}

• code è l'errore a livello HTTP, ad esempio UNAUTHORIZED, FORBIDDEN, NOT_FOUND, BAD_REQUEST o TOO_MANY_REQUESTS.
• data.reason, quando presente, è un motivo più preciso leggibile dalla macchina come auth.key_not_found o rate_limit.exceeded. Fai branching su questo piuttosto che su message, che è per le persone e può cambiare.
• defined è true quando l'operazione elenca quell'errore nella riferimento API, e false per errori che qualsiasi richiesta può incontrare (autenticazione, limiti di frequenza, una rotta sconosciuta).
• Un fallimento di validazione risponde BAD_REQUEST con i problemi in data.formErrors e data.fieldErrors.

Ogni risposta include anche un X-Request-ID. Citalo quando contatti l'assistenza, così possiamo trovare quella richiesta esatta.

Ogni risposta indica il limite contro cui è stata conteggiata, in due forme:

• le intestazioni X-RateLimit-*;
• i campi strutturati IETF RateLimit (stato attuale: r sono le richieste rimanenti, t i secondi fino al reset della finestra) e RateLimit-Policy (la quota: q è il limite, w la finestra in secondi).

Una 429 include anche Retry-After in secondi e data.retryAfterMs. Attendi almeno quel tempo prima della prossima richiesta; riprovare prima viene conteggiato e rifiutato di nuovo.

Un'operazione di scrittura che elenca un'intestazione Idempotency-Key nella riferimento API può essere ripetuta senza eseguire il lavoro due volte. Invia una chiave per ogni scrittura logica e ripeti la stessa chiave in ogni tentativo:

• la stessa chiave con lo stesso corpo entro 24 ore riproduce la risposta memorizzata;
• la stessa chiave con un corpo diverso viene rifiutata con 422;
• un duplicato che arriva mentre il primo è ancora in esecuzione riceve 409.

Un'operazione senza l'intestazione non è idempotente, quindi ripetila solo quando sai che il primo tentativo non è andato a buon fine.