type und verlinkt direkt auf den passenden Abschnitt
dieser Seite.
Aufbau des Envelopes
Endpunktspezifische Zusatzdaten wie
warnings, earliest oder code stehen kanonisch
in errors[0]._meta. Dieselben Werte erscheinen derzeit zusätzlich auf oberster Ebene.
Diese Duplikate sind eine Übergangslösung für ältere Clients und sollten in neuen
Integrationen nicht mehr ausgewertet werden.Fehlercodes
bad_request (HTTP 400)
Die Anfrage ist grundsätzlich fehlerhaft und konnte nicht verarbeitet werden.
Typische Auslöser: ungültiges JSON im Request-Body, ein fehlender oder falsch gesetzter
Content-Type, oder ein Pfadparameter in einem Format, das der Endpunkt nicht kennt.
unauthenticated (HTTP 401)
Es fehlt ein gültiger Zugangstoken.
Typische Auslöser: der Header Authorization: Bearer … fehlt, der Token wurde beim
Abmelden verworfen, oder der Token gehört zu einem anderen Mandanten als die aufgerufene
Subdomain. Neuen Token über POST /rest/login beziehen.
forbidden (HTTP 403)
Die Anmeldung ist gültig, der Zugriff aber nicht erlaubt.
Typische Auslöser: der angemeldeten Rolle fehlt die nötige Berechtigung, die angefragte
Person liegt außerhalb der sichtbaren Organisationseinheiten, oder das Modul zum Endpunkt
ist für den Mandanten nicht aktiviert.
not_found (HTTP 404)
Die angefragte Ressource existiert nicht.
Typische Auslöser: eine unbekannte oder bereits gelöschte ID, ein Tippfehler im Pfad,
oder eine Ressource, die zu einem anderen Mandanten gehört.
method_not_allowed (HTTP 405)
Der Pfad existiert, unterstützt aber die verwendete HTTP-Methode nicht.
Typische Auslöser: POST statt PUT beim Aktualisieren, oder ein Sammel-Endpunkt, der
nur lesend angeboten wird. Die erlaubten Methoden stehen im Response-Header Allow.
conflict (HTTP 409)
Die Anfrage ist an sich gültig, kollidiert aber mit dem aktuellen Zustand
der Daten.
Typische Auslöser: eine Zeitkorrektur in einem bereits abgeschlossenen Abrechnungsmonat,
eine Stempelung, die der Reihenfolge Kommen/Gehen widerspricht, oder eine Abwesenheit,
die sich mit einer bestehenden überschneidet. Details stehen in errors[0]._meta.
validation_error (HTTP 422)
Die Anfrage wurde verstanden, einzelne Felder halten aber die
Validierungsregeln nicht ein.
Typische Auslöser: Pflichtfelder fehlen, Datumsangaben liegen außerhalb des erlaubten
Bereichs, oder ein Wert entspricht keinem gültigen Enum-Fall. Die Feldmeldungen stehen
sowohl in field_errors als auch in errors[0]._meta.fields.
too_many_requests (HTTP 429)
Es wurden zu viele Anfragen in zu kurzer Zeit gestellt.
Typische Auslöser: wiederholte Loginversuche mit falschem Passwort, oder eine
Integration, die eine Liste ohne Pause durchläuft. Der Header Retry-After nennt die
Wartezeit in Sekunden. Am besten mit exponentiell wachsenden Wartezeiten erneut
versuchen.
server_error (HTTP 500)
Auf Serverseite ist ein unerwarteter Fehler aufgetreten.
Die Anfrage sollte unverändert wiederholt werden können. Tritt der Fehler erneut auf,
bitte den Support mit der request_id kontaktieren. Aus Sicherheitsgründen enthält
detail im Produktivbetrieb keine technischen Details.
service_unavailable (HTTP 503)
Der Dienst steht vorübergehend nicht zur Verfügung.
Typische Auslöser: Wartungsfenster oder ein nachgelagerter Dienst wie die
DATEV-Schnittstelle, der gerade nicht erreichbar ist. Nach kurzer Wartezeit erneut
versuchen.
Umgang mit Fehlern in Integrationen
1
Status auswerten, nicht den Text
Verzweigt eure Logik über den HTTP-Status oder den Code aus
errors[0].type.
Der Text in message und detail ist für Menschen gedacht und kann sich ändern.2
request_id mitloggen
Schreibt die
request_id in euer eigenes Log. Damit lässt sich jede Anfrage im
Support eindeutig zuordnen.3
Bei 429 und 503 erneut versuchen
Beide Fehler sind vorübergehend. Alle anderen Codes lösen sich nicht durch
Wiederholen, sondern erfordern eine Korrektur der Anfrage.
4
Validierungsfehler am Feld anzeigen
Nutzt
field_errors, um Meldungen direkt am betroffenen Eingabefeld auszugeben.