> ## 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.

# Troubleshooting

> Diagnostizieren Sie Erreichbarkeit, Authentifizierung, Scope, Validierung, Statuskonflikte, Throttling, Timeouts und Downloadfehler.

Beginnen Sie mit HTTP-Status, `error.code` und `X-Request-ID`. Wiederholen Sie während der Diagnose keine Schreibvorgänge blind.

## Triage-Ablauf

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart TD
    A[Anfrage fehlgeschlagen] --> B{Ist GET /health erreichbar?}
    B -- Nein --> C[DNS, TLS, Firewall, Proxy und Basis-URL prüfen]
    B -- Ja --> D{Geschützter Read erfolgreich?}
    D -- Nein --> E{Status}
    E -->|401| F[Key-Wert und aktiven Status prüfen]
    E -->|403| G[Tenant und Key-Scope prüfen]
    E -->|400 / 406| H[Header und Request-ID prüfen]
    E -->|429| I[Retry-After berücksichtigen]
    E -->|5xx| J[Backoff anwenden und Request-ID erfassen]
    D -- Ja --> K{Write oder Download schlägt fehl?}
    K -- Write --> L[Schema, Referenzen, Status und Dry Run prüfen]
    K -- Download --> M[Metadaten, fileName, Scope und Medientyp prüfen]
```

## Erreichbarkeit

| Symptom                                             | Prüfung                                                                         |
| --------------------------------------------------- | ------------------------------------------------------------------------------- |
| DNS- oder Verbindungsfehler                         | Basis-URL ist exakt `https://api.jobhandy.io/v1`; ausgehendes HTTPS ist erlaubt |
| TLS-Fehler                                          | System-Truststore, TLS-Inspection, Proxy-Konfiguration und Systemzeit           |
| `/health` schlägt fehl                              | Netzwerkpfad oder Verfügbarkeit des öffentlichen Dienstes                       |
| `/health` funktioniert, geschützter Read aber nicht | API-Key, Tenant-Scope oder Request-Header                                       |

## Authentifizierung und Scope

### `401 INVALID_API_KEY`

* Prüfen Sie, ob der Wert aus der vorgesehenen Secret-Version geladen wird.
* Prüfen Sie auf führende oder nachgestellte Leerzeichen und versehentliche Anführungszeichen.
* Prüfen Sie in der API-Key-Verwaltung, ob der Key aktiv ist.
* Prüfen Sie, ob bei der Rotation eine veraltete Runtime übersehen wurde.

### `403 TENANT_NOT_IN_SCOPE`

* Prüfen Sie, ob `X-Tenant-ID` eine Tenant-ID und kein Unternehmensname oder keine Divisions-ID enthält.
* Prüfen Sie, ob der ausgewählte Tenant im Key-Scope enthalten ist.
* Prüfen Sie, ob die referenzierte Ressource zum selben autorisierten Kontext gehört.

### Mehrdeutige Zuordnung

Senden Sie `X-Tenant-ID` und beim Erstellen von Mitarbeitern, falls erforderlich, eine zulässige `divisionId`.

## Request-Validierung

| Fehler                        | Prüfung                                                                                                                         |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `UNKNOWN_QUERY_PARAMETER`     | Parametername und Unterstützung durch den Endpoint                                                                              |
| `UNSUPPORTED_HEADER`          | Nicht vertraglich vorgesehene Request-Header entfernen                                                                          |
| `INVALID_FILTER_SYNTAX`       | Anführungszeichen, escapte Apostrophe, Klammern und Kommas in `IN`                                                              |
| `UNSUPPORTED_FILTER_FIELD`    | Endpointspezifische Feldliste                                                                                                   |
| `UNSUPPORTED_FILTER_OPERATOR` | Zum Feld kompatibler Operator                                                                                                   |
| `UNSUPPORTED_SORT_FIELD`      | Genau ein dokumentiertes skalares Feld                                                                                          |
| `UNSUPPORTED_MEDIA_TYPE`      | `application/json` oder dokumentierter Multipart-Typ                                                                            |
| `PAYLOAD_TOO_LARGE`           | Vollständiger JSON- oder Multipart-Body unter 5 MiB                                                                             |
| `VALIDATION_ERROR`            | Pflichtfelder, Formate, Enum-Schreibweise, Nullability und unbekannte Eigenschaften                                             |
| `EMPLOYEE_NOT_ACTIVATED`      | Die Aktivierung des referenzierten Mitarbeiters ist noch nicht abgeschlossen; Aktivierung vor der Vorfallerstellung abschließen |

## Statuskonflikte

Lesen Sie bei `409` die Ressource erneut, bevor Sie handeln.

* `ORDER_ALREADY_DECIDED`: aktuellen finalen Entscheidungsstatus abgleichen.
* `INVALID_STATE_TRANSITION`: der aktuelle Lifecycle erlaubt die Anfrage nicht.
* `DIVISION_CYCLE`: ausgewählter Parent ist ein Nachfahre der Division.
* `DIVISION_NAME_NOT_UNIQUE_ON_SAME_LEVEL`: eindeutigen Geschwisternamen wählen.
* `DUPLICATE_RESOURCE`: vorhandene Ressource finden und zuordnen.

## Timeout nach einem Schreibvorgang

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart TD
    A[Client-Timeout] --> B[Nicht von einem Fehlschlag ausgehen]
    B --> C[Betroffene Ressource lesen oder suchen]
    C --> D{Gewünschtes Ergebnis vorhanden?}
    D -- Ja --> E[Als Erfolg abgleichen]
    D -- Nein --> F{Replay nach Statusprüfung sicher?}
    F -- Ja --> G[Mit neuer Request-ID wiederholen]
    F -- Nein --> H[Manuelle Klärung]
```

## Downloadfehler

* Metadaten erneut lesen und prüfen, dass `fileName` nicht `null` ist.
* Prüfen, ob die ID zum erwarteten Tenant gehört.
* Status und `Content-Type` prüfen, bevor die Response auf Datenträger geschrieben wird.
* Unvollständige Dateien nach `502`, `503`, `504` oder Netzwerkunterbrechung verwerfen.
* Transiente Downloadfehler mit begrenztem Backoff wiederholen.

## Datensatz für die Eskalation

Erfassen Sie:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
UTC-Zeitstempel
Methode und Pfad
HTTP-Status
error.code und error.message
X-Request-ID / error.requestId
Tenant-Kontext
Anzahl der Versuche
ob dryRun verwendet wurde
bereinigte Reproduktionsschritte
```

Fügen Sie niemals den API-Key oder unnötige vollständige personenbezogene Payloads bei.