API-Fehlerformat und Fehlercodes

Jede Fehlerantwort der API hat dasselbe Format. Dein Code sollte sich auf den Fehlercode im Feld error verlassen, nicht auf den Text in message – der Code bleibt stabil, der Text kann sich ändern und erscheint in der Kontosprache.

#Aufbau einer Fehlerantwort

{
  "error": "validation_failed",
  "message": "Some of the information provided is invalid. Please check and try again.",
  "details": [
    { "field": "title", "reason": "minLength", "message": "…" }
  ],
  "request_id": "6b1f0c2e-…"
}

error

Maschinenlesbarer Code, zum Beispiel not_found. Bei den meisten Fehlern steht er zusätzlich im Header X-Error-Code – verlass dich aber auf das Feld im Body.

message

Lesbare Beschreibung in der Kontosprache: mit API-Key die des Workspace-Eigentümers, mit einer verbundenen App die der Person, die sie verbunden hat. Ohne gültigen Token – etwa bei 401 aus der Token-Prüfung – richtet sich die Sprache nach Accept-Language, sonst Englisch. Der Header Content-Language nennt die Sprache.

details

Nur wenn es mehr zu sagen gibt. Bei 422 aus der Eingabeprüfung eine Liste mit field, reason und message pro Problem; bei 422 aus der Fachlogik und allen anderen Fehlern ein Objekt, etwa mit reason, retry_after_sec oder einer Liste von issues. Bei einer überschrittenen Größe enthält es field, reason und limit, bei 413 request_too_large max_bytes und max_kb. Prüfe also, ob details eine Liste ist.

request_id

Die ID der Anfrage. Sie steht auch im Header X-Request-Id. Gib sie bei Fragen an den Support mit an.

Ausnahmen: Die Antwort bei 429 rate_limited hat statt details das Feld retry_after_sec; bei 429 und 403 insufficient_scope fehlt request_id im Body. 401 aus der Token-Prüfung und 422 aus der Schema-Prüfung haben keinen Header X-Error-Code, und bei der Schema-Prüfung ist nur das oberste message übersetzt, die Texte in details bleiben englisch. Der Header X-Request-Id ist immer gesetzt.

#Die wichtigsten Codes

#Eingabefehler lesen

Bei 422 validation_failed nennt details jedes Problem einzeln: field ist der Pfad des Feldes (bei verschachtelten Objekten mit Schrägstrichen, etwa theme_config/button_style), reason die verletzte Regel wie required, minLength, maxLength, enum oder additionalProperties. Bei additionalProperties steht in der Meldung, welche Felder unbekannt sind – häufig ein Tippfehler im Feldnamen.

#Empfohlene Reaktion im Code

• 400, 413 und 422: nicht wiederholen, sondern die Anfrage korrigieren
• 401 invalid_token: einmal ein neues Token holen und wiederholen
• 403: nicht wiederholen; Scope, Plan oder Zuständigkeit prüfen
• 404: ID prüfen; nach einem Löschen ist das normal
• 409: Zustand neu laden und entscheiden, ob die Aktion noch nötig ist
• 429: warten laut Retry-After und dann wiederholen – siehe Rate Limits
• 500 und 503: mit wachsenden Pausen wenige Male wiederholen