API-Fehlercodes verstehen
Die Werkzettel-API folgt den HTTP-Standards: Der Statuscode sagt, was passiert ist, und der Antwortkörper liefert Details, mit denen eure Integration gezielt reagieren kann. Fehler haben ein stabiles Format mit Code und Message — ihr sollt nicht auf Texte parsen, sondern auf die Codes reagieren.
Die Codes, die im Alltag vorkommen:
- 400 Bad Request — die Anfrage ist fehlerhaft: Pflichtfeld fehlt, Datum im falschen Format, Wert außerhalb des erlaubten Bereichs. Prüft eure Payload, bevor ihr dieselbe Anfrage erneut schickt.
- 401 Unauthorized — fehlende oder abgelaufene Authentifizierung. Kein Token mitgesendet oder die Session ist abgelaufen. Reaktion: Neu einloggen (siehe Auth-Flow) und den Request mit frischem Token wiederholen.
- 403 Forbidden — das Token ist gültig, aber die Berechtigung fehlt: falsche Rolle, fremder Mandant oder ein Endpunkt, den euer Konto nicht nutzen darf. Hier hilft kein Re-Login — ihr braucht die richtige Rolle oder einen anderen Zugang.
- 404 Not Found — die Ressource gibt es im Kontext dieses Mandanten nicht. Prüft IDs und slugs; besonders bei IDs aus fremden Mandanten antwortet die API absichtlich mit 404, um Daten anderer Betriebe nicht einmal indirekt zu verraten.
- 409 Conflict — die Änderung kollidiert mit einem bestehenden Stand, etwa bei doppelten Einträgen oder parallelen Änderungen. Lest den aktuellen Stand und entscheidet erneut.
- 429 Too Many Requests — Rate-Limit. Wartet gemäß Retry-Hinweis, statt sofort erneut zu feuern.
- 5xx — Fehler auf unserer Seite. Wiederholen mit Backoff; persistiert das Problem, meldet es mit Request-IDs an den Support.
Faustregel für saubere Integrationen: Erst 401 durch Re-Login behandeln, dann 403 als Konfigurationsfehler escalation-fähig machen, alles 5xx nur mit exponentiellem Backoff wiederholen.