> ## Documentation Index > Fetch the complete documentation index at: https://docs.stampfactory.eu/llms.txt > Use this file to discover all available pages before exploring further. # Fehlerreferenz > Aufbau des Fehler-Envelopes und Bedeutung aller Fehlercodes der Stampfactory API Alle Fehlerantworten der Stampfactory API (Status 4xx und 5xx) haben denselben Aufbau. Der Fehlercode steckt im Feld `type` und verlinkt direkt auf den passenden Abschnitt dieser Seite. ## Aufbau des Envelopes ```json theme={null} { "request_id": "9f1c2f7e-5b3c-4a11-9a1d-2f0a5c7d3e88", "timestamp": "2026-07-25T06:00:00Z", "message": "Menschlich lesbare Meldung", "errors": [ { "title": "Not Found", "detail": "Menschlich lesbare Meldung", "type": "https://docs.stampfactory.eu/errors#not_found", "_meta": { "path": "/rest/employees/9d3f8c1a" } } ] } ``` | Feld | Beschreibung | | ----------------- | --------------------------------------------------------------------------------------------------------------------- | | `request_id` | Korrelations-ID der Anfrage, identisch mit dem Response-Header `X-Request-Id`. Bitte bei Supportanfragen mitschicken. | | `timestamp` | Zeitpunkt der Fehlerantwort, ISO 8601 in UTC. | | `message` | Menschlich lesbare Meldung. Bei Validierungsfehlern die erste Feldmeldung. | | `field_errors` | Nur bei Status 422: Zuordnung Feldname zu Liste von Meldungen. | | `errors` | Liste mit genau einem Fehlerobjekt (`title`, `detail`, `type`, `_meta`). | | `errors[0]._meta` | Maschinenlesbare Zusatzdaten. Enthält immer `path`, bei 422 zusätzlich `fields`. | 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. ```json theme={null} { "request_id": "1f2b8d44-0c6e-4d0e-8e7c-1a1c3d5f7a90", "timestamp": "2026-07-25T06:00:00Z", "message": "Malformed JSON in request body.", "errors": [ { "title": "Bad Request", "detail": "Malformed JSON in request body.", "type": "https://docs.stampfactory.eu/errors#bad_request", "_meta": { "path": "/rest/employees" } } ] } ```
### `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. ```json theme={null} { "request_id": "2a7f1c90-3b62-4c8a-9c1e-7d4f2b6a8c11", "timestamp": "2026-07-25T06:00:00Z", "message": "Unauthenticated.", "errors": [ { "title": "Unauthenticated", "detail": "Unauthenticated.", "type": "https://docs.stampfactory.eu/errors#unauthenticated", "_meta": { "path": "/rest/employees" } } ] } ```
### `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. ```json theme={null} { "request_id": "3c9d4e21-8a55-4f10-b2d3-6e8a1c4f9b02", "timestamp": "2026-07-25T06:00:00Z", "message": "This action is unauthorized.", "errors": [ { "title": "Forbidden", "detail": "This action is unauthorized.", "type": "https://docs.stampfactory.eu/errors#forbidden", "_meta": { "path": "/rest/employees/9d3f8c1a" } } ] } ```
### `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. ```json theme={null} { "request_id": "4d0e5f32-9b66-4021-a3e4-7f9b2d5a0c13", "timestamp": "2026-07-25T06:00:00Z", "message": "The endpoint /rest/employees/9d3f8c1a returned an error.", "errors": [ { "title": "Not Found", "detail": "The endpoint /rest/employees/9d3f8c1a returned an error.", "type": "https://docs.stampfactory.eu/errors#not_found", "_meta": { "path": "/rest/employees/9d3f8c1a" } } ] } ```
### `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`. ```json theme={null} { "request_id": "5e1f6043-0c77-4132-b4f5-80ac3e6b1d24", "timestamp": "2026-07-25T06:00:00Z", "message": "The GET method is not supported for this route. Supported methods: POST.", "errors": [ { "title": "Method Not Allowed", "detail": "The GET method is not supported for this route. Supported methods: POST.", "type": "https://docs.stampfactory.eu/errors#method_not_allowed", "_meta": { "path": "/rest/mobile" } } ] } ```
### `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`. ```json theme={null} { "request_id": "6f2a7154-1d88-4243-c506-91bd4f7c2e35", "timestamp": "2026-07-25T06:00:00Z", "message": "Der Monat 2026-06 ist bereits abgeschlossen.", "errors": [ { "title": "Conflict", "detail": "Der Monat 2026-06 ist bereits abgeschlossen.", "type": "https://docs.stampfactory.eu/errors#conflict", "_meta": { "path": "/rest/employees/9d3f8c1a/working_time", "code": "payroll_period_locked", "period": "2026-06" } } ] } ```
### `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`. ```json theme={null} { "request_id": "703b8265-2e99-4354-d617-a2ce508d3f46", "timestamp": "2026-07-25T06:00:00Z", "message": "Das Feld Code ist erforderlich.", "field_errors": { "code": ["Das Feld Code ist erforderlich."], "name": ["Das Feld Name ist erforderlich."] }, "errors": [ { "title": "Validation Error", "detail": "The given data was invalid.", "type": "https://docs.stampfactory.eu/errors#validation_error", "_meta": { "path": "/rest/employees", "fields": { "code": ["Das Feld Code ist erforderlich."], "name": ["Das Feld Name ist erforderlich."] } } } ] } ```
### `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. ```json theme={null} { "request_id": "814c9376-3faa-4465-e728-b3df619e4057", "timestamp": "2026-07-25T06:00:00Z", "message": "Too Many Attempts.", "errors": [ { "title": "Too Many Requests", "detail": "Too Many Attempts.", "type": "https://docs.stampfactory.eu/errors#too_many_requests", "_meta": { "path": "/rest/login" } } ] } ```
### `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. ```json theme={null} { "request_id": "925daa87-40bb-4576-f839-c4ea72af5168", "timestamp": "2026-07-25T06:00:00Z", "message": "An internal server error occurred.", "errors": [ { "title": "Server Error", "detail": "An internal server error occurred.", "type": "https://docs.stampfactory.eu/errors#server_error", "_meta": { "path": "/rest/working_time/2026-07-01/2026-07-31" } } ] } ```
### `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. ```json theme={null} { "request_id": "a36ebb98-51cc-4687-0a4a-d5fb83b06279", "timestamp": "2026-07-25T06:00:00Z", "message": "Service Unavailable.", "errors": [ { "title": "Service Unavailable", "detail": "Service Unavailable.", "type": "https://docs.stampfactory.eu/errors#service_unavailable", "_meta": { "path": "/rest/datev/status" } } ] } ``` ## Umgang mit Fehlern in Integrationen 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. Schreibt die `request_id` in euer eigenes Log. Damit lässt sich jede Anfrage im Support eindeutig zuordnen. Beide Fehler sind vorübergehend. Alle anderen Codes lösen sich nicht durch Wiederholen, sondern erfordern eine Korrektur der Anfrage. Nutzt `field_errors`, um Meldungen direkt am betroffenen Eingabefeld auszugeben.