Fehler und Statuscodes
Fehler sind JSON, immer in derselben Struktur, und tragen immer einen stabilen maschinenlesbaren Code. Verzweigen Sie über den Code, nicht über die Meldung.
Die Struktur
Jeder Fehlschlag liefert ein Objekt mit einer für Menschen lesbaren error-Meldung und einem stabilen code. Die Meldung ist für Menschen geschrieben und kann umformuliert werden; der Code ist eine Zusage und ändert sich nicht unter Ihnen weg.
{
"error": "That file is larger than the 200 MB limit on your plan.",
"code": "VALIDATION_FAILED"
}Codes, die Sie behandeln sollten
| Code | HTTP | Bedeutung |
|---|---|---|
| NOT_AUTHENTICATED | 401 | Bearer-Token fehlt oder ist fehlerhaft |
| FORBIDDEN | 403 | Der Schlüssel ist gültig, darf dies aber nicht |
| NOT_ENTITLED | 402 | Der Tarif des Kontos enthält keinen API-Zugang |
| VALIDATION_FAILED | 400 / 413 | Fehlerhafte Anfrage, nicht unterstützte Umwandlung oder zu große Datei |
| NOT_FOUND | 404 | Kein solcher Auftrag, oder er gehört einem anderen Konto |
| RATE_LIMITED | 429 | Stundenlimit erreicht. Warten und erneut versuchen. |
| INTERNAL | 500 | Auf unserer Seite ist etwas kaputtgegangen. Erneuter Versuch unbedenklich. |
Was einen erneuten Versuch lohnt
429 und 500 lohnen einen erneuten Versuch, mit Verzögerung — mit wachsendem Abstand statt in einer Schleife, denn erneute Versuche zählen wie alles andere gegen Ihr Stundenlimit.
Alles Übrige ist für diese Anfrage endgültig. Ein 400, 402 oder 404 erneut zu versuchen, liefert dieselbe Antwort und verbraucht dabei Ihr Ratenkontingent.
Ein 502 oder 503 ohne JSON-Rumpf stammt nicht aus der Anwendung — das ist der vorgelagerte Proxy, und dort lohnt ein erneuter Versuch immer.