Błędy i kody stanu
Błędy są w JSON-ie, zawsze o tym samym kształcie, i zawsze niosą stabilny kod czytelny maszynowo. Rozgałęziaj się po kodzie, nie po komunikacie.
Kształt
Każde niepowodzenie zwraca obiekt z czytelnym dla człowieka polem error i stabilnym code. Komunikat jest pisany dla człowieka i może zostać przeredagowany; kod jest zobowiązaniem i nie zmieni się bez uprzedzenia.
{
"error": "That file is larger than the 200 MB limit on your plan.",
"code": "VALIDATION_FAILED"
}Kody, które warto obsłużyć
| Kod | HTTP | Znaczenie |
|---|---|---|
| NOT_AUTHENTICATED | 401 | Brak tokenu bearer albo token źle sformułowany |
| FORBIDDEN | 403 | Klucz jest poprawny, ale nie ma do tego uprawnień |
| NOT_ENTITLED | 402 | Plan konta nie obejmuje dostępu do API |
| VALIDATION_FAILED | 400 / 413 | Błędne żądanie, nieobsługiwana konwersja albo za duży plik |
| NOT_FOUND | 404 | Nie ma takiego zadania albo należy ono do innego konta |
| RATE_LIMITED | 429 | Osiągnięto limit godzinowy. Odczekaj i spróbuj ponownie. |
| INTERNAL | 500 | Coś zepsuło się po naszej stronie. Ponowienie jest bezpieczne. |
Co warto ponawiać
429 i 500 warto ponowić, z opóźnieniem — z narastającym odstępem zamiast w pętli, bo ponowienia liczą się do limitu godzinowego jak każde inne żądanie.
Cała reszta jest trwała dla tego żądania. Ponawianie 400, 402 czy 404 daje tę samą odpowiedź i zużywa limit na dowiedzenie się tego.
502 lub 503 bez treści JSON nie pochodzi z aplikacji — to proxy stojące przed nią, a tam ponowienie zawsze ma sens.