Errori e codici di stato
Gli errori sono JSON, sempre della stessa forma, e portano sempre un codice stabile leggibile dalle macchine. Ramifica sul codice, non sul messaggio.
La forma
Ogni fallimento restituisce un oggetto con un error leggibile da una persona e un code stabile. Il messaggio è scritto per una persona e può essere riformulato; il codice è un impegno e non cambierà alle tue spalle.
{
"error": "That file is larger than the 200 MB limit on your plan.",
"code": "VALIDATION_FAILED"
}Codici da gestire
| Codice | HTTP | Significato |
|---|---|---|
| NOT_AUTHENTICATED | 401 | Token bearer mancante o malformato |
| FORBIDDEN | 403 | La chiave è valida ma non è autorizzata a farlo |
| NOT_ENTITLED | 402 | Il piano dell’account non include l’accesso all’API |
| VALIDATION_FAILED | 400 / 413 | Richiesta errata, conversione non supportata o file troppo grande |
| NOT_FOUND | 404 | Nessun lavoro con quell’identificativo, o appartiene a un altro account |
| RATE_LIMITED | 429 | Limite orario raggiunto. Attendi e riprova. |
| INTERNAL | 500 | Qualcosa si è rotto dalla nostra parte. Riprovare è sicuro. |
Cosa vale la pena ritentare
429 e 500 vale la pena ritentarli, con un ritardo — allontanando i tentativi invece di ciclare, perché i tentativi contano sul tuo limite orario come qualsiasi altra richiesta.
Tutto il resto è definitivo per quella richiesta. Ritentare un 400, un 402 o un 404 produce la stessa risposta e consuma la tua quota per scoprirlo.
Un 502 o 503 senza corpo JSON non arriva dall’applicazione: è il proxy davanti a essa, e lì vale sempre la pena riprovare.