Fehler der Plattform-API sind maschinenlesbar: ein stabiler code für deine Fehlerbehandlung, eine message für Menschen. Diese Seite beschreibt die Envelope und die Status-Codes, auf die sich Integrationen einstellen sollten.
Fehler-Envelope
Jede Fehlerantwort trägt denselben JSON-Aufbau:
codeist stabil und für programmatische Auswertung gedacht. Verlasse dich aufcode, nie auf den Wortlaut vonmessage.detailsist optional und enthält bei Validierungsfehlern die betroffenen Felder.
HTTP-Status-Codes
| Status | Code (typisch) | Bedeutung | Wiederholen? |
|---|---|---|---|
| 400 | validation_failed | Anfrage fehlerhaft (Body, Parameter) | Nein, erst korrigieren |
| 401 | unauthorized | Kein oder ungültiger API-Key | Nein |
| 403 | forbidden | Key gültig, Aktion nicht erlaubt (Scope/Rechte) | Nein |
| 404 | not_found | Ressource existiert nicht oder gehört einem anderen Workspace | Nein |
| 409 | conflict | Zustand kollidiert (z.B. doppelter eindeutiger Wert) | Nach Prüfung |
| 429 | rate_limited | Zu viele Anfragen | Ja, nach Retry-After |
| 500 | internal_error | Unerwarteter Fehler auf Plattform-Seite | Ja, mit Backoff |
| 503 | unavailable | Vorübergehend nicht verfügbar (Wartung, Überlast) | Ja, mit Backoff |
Umgang mit Fehlern
- Auf
codeverzweigen,messagenur loggen oder anzeigen. - 5xx und 429 mit exponentiellem Backoff wiederholen, 4xx (außer 429) nicht.
- Schreiboperationen idempotent gestalten, damit ein wiederholter Request nach Timeout keine Duplikate erzeugt.
- Bei anhaltenden 5xx die Status-Seite prüfen (status.reosa.de), bevor du eskalierst.