> ## Documentation Index > Fetch the complete documentation index at: https://developers.jobhandy.io/llms.txt > Use this file to discover all available pages before exploring further. # Fehlerbehandlung > Interpretieren Sie das einheitliche Fehler-Envelope, klassifizieren Sie Fehler, entscheiden Sie über Retries und erfassen Sie verwertbare Diagnosedaten. Jeder öffentliche API-Fehler verwendet dieses Envelope: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "error": { "code": "VALIDATION_ERROR", "message": "The request could not be validated.", "requestId": "018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4" } } ``` Verwenden Sie den HTTP-Status für die grobe Fehlerklasse und `error.code` für die präzise Behandlung. ## Entscheidungsablauf ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} flowchart TD A[API-Response ist nicht erfolgreich] --> B{HTTP-Status} B -->|400 / 406 / 413 / 415 / 422| C[Anfrage oder Daten korrigieren] B -->|401| D[API-Key und aktiven Status prüfen] B -->|403| E[Tenant und API-Key-Scope prüfen] B -->|404| F[ID, Scope und Dateiverfügbarkeit prüfen] B -->|409| G[Ressourcenstatus erneut lesen] B -->|429| H[Retry-After berücksichtigen] B -->|500 / 502 / 503 / 504| I[Nur wiederholen, wenn Replay sicher ist] ``` ## Fehlerkatalog | Fehlercode | Typische HTTP-Klasse | Bedeutung | Client-Maßnahme | Retry | | ---------------------------------------- | -------------------: | ------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ------: | | `INVALID_API_KEY` | `401` | Key fehlt, ist ungültig, gelöscht oder inaktiv | Zugangsdaten ersetzen oder reaktivieren | Nein | | `INVALID_REQUEST_ID` | `400` | Request-ID ist keine UUID v4 oder v7 | Gültigen Wert erzeugen | Nein | | `NOT_ACCEPTABLE` | `406` | Angeforderte Response-Repräsentation ist nicht verfügbar | `Accept` korrigieren | Nein | | `UNSUPPORTED_MEDIA_TYPE` | `415` | Request-Medientyp wird nicht akzeptiert | Dokumentierten Content-Type verwenden | Nein | | `MISSING_ATTACHMENT` | `400` / `422` | Multipart-Request enthält keinen erforderlichen Upload | Erforderliches Feld `uploads` hinzufügen | Nein | | `PAYLOAD_TOO_LARGE` | `413` | Vollständiger Request überschreitet 5 MiB | JSON- oder Multipart-Größe reduzieren | Nein | | `UNKNOWN_QUERY_PARAMETER` | `400` | Query-Parameter wird nicht unterstützt | Unbekannten Parameter entfernen | Nein | | `UNSUPPORTED_HEADER` | `400` | Header wird nicht akzeptiert | Header entfernen oder korrigieren | Nein | | `NOT_FOUND` | `404` | Ressource fehlt oder ist im Scope nicht sichtbar | ID und Tenant-Kontext prüfen | Nein | | `FILE_NOT_FOUND` | `404` | Referenzierte Datei ist nicht verfügbar | Metadaten und Verfügbarkeit erneut lesen | Nein | | `TENANT_CONTEXT_AMBIGUOUS` | `400` / `422` | Es kann kein eindeutiger Ziel-Tenant bestimmt werden | `X-Tenant-ID` senden | Nein | | `EMPLOYEE_PLACEMENT_AMBIGUOUS` | `422` | Mitarbeiterzuordnung ergibt keine eindeutige zulässige Division | Erlaubte `divisionId` senden | Nein | | `TENANT_NOT_IN_SCOPE` | `403` | Tenant liegt außerhalb des Key-Scopes | Scope oder Tenant korrigieren | Nein | | `INVALID_REFERENCE_ID` | `400` / `422` | Referenz-ID besitzt ein ungültiges Format | Eine von JobHandy zurückgegebene ID verwenden | Nein | | `INVALID_REFERENCE` | `404` / `422` | Referenzierte Ressource fehlt oder ist nicht verfügbar | Referenz und Scope erneut lesen | Nein | | `VALIDATION_ERROR` | `422` | Anfrage verletzt Schema- oder fachliche Validierung | Payload korrigieren | Nein | | `INVALID_FILTER_SYNTAX` | `400` / `422` | Filter kann nicht geparst werden | Quoting und Ausdruck korrigieren | Nein | | `UNSUPPORTED_FILTER_FIELD` | `422` | Feld ist nicht filterbar | Vom Endpoint unterstütztes Feld verwenden | Nein | | `UNSUPPORTED_FILTER_OPERATOR` | `422` | Operator ist für das Feld ungültig | Unterstützten Operator verwenden | Nein | | `UNSUPPORTED_SORT_FIELD` | `422` | Sortierfeld ist nicht verfügbar | Dokumentiertes skalares Feld verwenden | Nein | | `UNSUPPORTED_FIELD` | `422` | Feld ist nicht schreibbar oder auswählbar | Nicht unterstütztes Feld entfernen | Nein | | `EMPLOYEE_BLOCKED` | `409` / `422` | Mitarbeiterstatus verhindert die Operation | Mitarbeiterstatus korrigieren | Nein | | `EMPLOYEE_NOT_ACTIVATED` | `422` | Für den referenzierten Mitarbeiter ist die Aktivierung noch nicht abgeschlossen | Aktivierung abschließen und anschließend eine neue Anfrage senden | Nein | | `DIVISION_CYCLE` | `409` / `422` | Parent-Änderung würde einen Hierarchiezyklus erzeugen | Gültigen Parent wählen | Nein | | `DIVISION_NAME_NOT_UNIQUE_ON_SAME_LEVEL` | `409` | Geschwistername existiert bereits | Eindeutigen Namen auf derselben Ebene verwenden | Nein | | `DUPLICATE_RESOURCE` | `409` | Eindeutigkeitsregel wird verletzt | Vorhandene Ressource finden und abgleichen | Nein | | `INVALID_STATE_TRANSITION` | `409` | Angeforderter Lifecycle-Übergang ist nicht zulässig | Zustand erneut lesen und blinde Retries stoppen | Nein | | `ORDER_ALREADY_DECIDED` | `409` | HR-Entscheidung ist bereits final | Erneut lesen und abgleichen | Nein | | `RATE_LIMIT_EXCEEDED` | `429` | Kontingent des API-Keys ist ausgeschöpft | `Retry-After` berücksichtigen | Ja | | `BAD_GATEWAY` | `502` | Upstream-Abhängigkeit ist fehlgeschlagen | Nur sichere Reads/Downloads wiederholen | Bedingt | | `SERVICE_UNAVAILABLE` | `503` | Dienst oder Abhängigkeit ist nicht verfügbar | Backoff; Writes abgleichen | Bedingt | | `GATEWAY_TIMEOUT` | `504` | Abhängigkeit ist in einen Timeout gelaufen | Backoff; Writes abgleichen | Bedingt | | `INTERNAL_SERVER_ERROR` | `500` | Unerwarteter Serverfehler | Request-ID protokollieren und nur bei sicherem Replay wiederholen | Bedingt | Die exakten Statuscodes und Fehler, die für eine Operation verfügbar sind, werden maßgeblich in der OpenAPI-Response-Liste des jeweiligen Endpoints dokumentiert. ## Diagnosedatensatz Speichern Sie für jeden fehlgeschlagenen Versuch: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} UTC-Zeitstempel HTTP-Methode Pfadtemplate, nicht eine URL mit Secrets HTTP-Status error.code error.message error.requestId / X-Request-ID Tenant-Kontext Versuchsnummer ID der logischen Operation ``` Speichern Sie weder den API-Key noch unnötige personenbezogene Daten. Führen Sie die operationsspezifischen Prüfungen durch, bevor Sie eine Supportanfrage eröffnen.