Fehlerbehandlung
Verstehen Sie API-Fehler mit klaren Hinweisen zu HTTP-Statuscodes und maschinenlesbaren Antwortinhalten.
Die Blazelock API verwendet standardisierte HTTP-Statuscodes, um anzuzeigen, ob eine Anfrage erfolgreich war oder fehlgeschlagen ist, und gibt maschinenlesbare Fehler Responses zurück, damit Ihre Anbindung vorhersehbar reagieren kann.
Im Allgemeinen stehen Statuscodes im 2xx-Bereich für erfolgreiche Anfragen. Statuscodes im 4xx-Bereich zeigen an, dass die Anfrage aufgrund der übermittelten Daten oder des aktuellen Kontexts fehlgeschlagen ist. Statuscodes im 5xx-Bereich weisen auf einen Fehler auf Seiten von Blazelock hin.
Format von Fehler Responses
Fehler Responses sind JSON-Objekte. Jede Fehler Response enthält einen maschinenlesbaren code und eine menschenlesbare message.
Über den Header Content-Language können Sie einen zweistelligen ISO-Sprachcode angeben. Wir geben die message dann in dieser Sprache aus. Weitere Informationen finden Sie unter Antwortsprache.
| Feld | Typ | Beschreibung |
|---|---|---|
code | string | Stabiler, maschinenlesbarer Fehlerbezeichner. |
message | string | Menschenlesbare Beschreibung des Problems. |
validation | object | Bei Validierungsfehlern vorhanden. Ordnet Feldnamen oder Feldpfade Arrays mit Fehlermeldungen zu. |
Beispiel für eine Fehler Response:
{
"code": "unauthenticated",
"message": "You must be authenticated to perform this action."
}Häufige Fehlertypen
Dies sind die häufigsten Fehlerfälle, die Ihre Anbindung behandeln sollte:
| HTTP-Status | Fehlercode | Beschreibung |
|---|---|---|
401 | unauthenticated | Für die Anfrage fehlt ein gültiger API-Schlüssel. Stellen Sie sicher, dass Sie Authorization: Bearer <api-key> senden. Siehe Authentifizierung. |
403 | forbidden | Die Anfrage ist authentifiziert, aber die Aktion ist nicht erlaubt. |
404 | resource_not_found | Die angeforderte Ressource konnte nicht gefunden werden oder ist im aktuellen Kontext nicht zugänglich. |
422 | validation | Ein oder mehrere Request-Felder haben die Validierung nicht bestanden. Siehe Validierungsfehler. |
429 | throttle_requests | Die Anfrage wurde aufgrund der Ratenbegrenzung abgelehnt. Siehe Ratenbegrenzung. |
500 | uncaught_error | Beim Verarbeiten der Anfrage ist ein unerwarteter Serverfehler aufgetreten. |
Validierungsfehler
Bei Validierungsfehlern stellen wir detaillierte Informationen zu jeder fehlgeschlagenen Validierung bereit.
Das Feld message enthält eine allgemeine Zusammenfassung des Validierungsfehlers. Das Feld validation enthält die Detailfehler als Objekt, dessen Schlüssel die betroffenen Feldnamen oder Feldpfade sind und dessen Werte Arrays mit Fehlermeldungen sind.
Bei verschachtelten Eingaben und Array-Eingaben werden Feldpfade in Dot-Notation ausgegeben, zum Beispiel users.0.email.
Auch die Texte von Validierungsfehlern können Sie über den Content-Language Header in einer passenden Sprache ausgeben lassen. Weitere Informationen finden Sie unter Antwortsprache.
Beispiel für eine Validierungsantwort:
{
"code": "validation",
"message": "The my_field_name field must not be greater than 255 characters.",
"validation": {
"my_field_name": [
"The my_field_name field must not be greater than 255 characters."
]
}
}Endpoint-spezifische Fehler
Diese Seite erklärt das allgemeine Fehlerverhalten der API.
Einige Endpunkte können zusätzliche Fehler zurückgeben, abhängig von ihren spezifischen Validierungsregeln oder ihrem Verhalten. Prüfen Sie in diesen Fällen die Dokumentation des jeweiligen Endpunkts in der API-Referenz.
Best Practices
- Statuscodes prüfen: Prüfen Sie immer zuerst die HTTP-Statuscodes, um die grobe Fehlerkategorie zu bestimmen.
- Fehlerdetails auslesen: Lesen Sie das Fehlerobjekt aus, um detaillierte Informationen zu erhalten.
- Retries mit Bedacht umsetzen: Wiederholen Sie Anfragen nur bei 5xx-Fehlern oder wenn dies ausdrücklich empfohlen wird.
- Vollständige Fehler protokollieren: Protokollieren Sie die vollständige Fehlerantwort zu Debugging-Zwecken.