Stampfactory

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

{
  "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"
      }
    }
  ]
}
FeldBeschreibung
request_idKorrelations-ID der Anfrage, identisch mit dem Response-Header X-Request-Id. Bitte bei Supportanfragen mitschicken.
timestampZeitpunkt der Fehlerantwort, ISO 8601 in UTC.
messageMenschlich lesbare Meldung. Bei Validierungsfehlern die erste Feldmeldung.
field_errorsNur bei Status 422: Zuordnung Feldname zu Liste von Meldungen.
errorsListe mit genau einem Fehlerobjekt (title, detail, type, _meta).
errors[0]._metaMaschinenlesbare Zusatzdaten. Enthält immer path, bei 422 zusätzlich fields.
Hinweis

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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

iRULU eXpro X1Plus Terminal

Ersteinrichtung des iRULU Zeiterfassungsterminals

Changelog

Alle Neuerungen, Verbesserungen und Fehlerbehebungen in Stampfactory

On this page

Aufbau des EnvelopesFehlercodesbad_request (HTTP 400)unauthenticated (HTTP 401)forbidden (HTTP 403)not_found (HTTP 404)method_not_allowed (HTTP 405)conflict (HTTP 409)validation_error (HTTP 422)too_many_requests (HTTP 429)server_error (HTTP 500)service_unavailable (HTTP 503)Umgang mit Fehlern in Integrationen