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

# Request-IDs und Korrelation

> Verwenden Sie X-Request-ID zur Korrelation von Clients, API-Responses, Retries, Logs und Supportanalysen.

Senden Sie bei jedem Request-Versuch eine UUID v4 oder v7 in `X-Request-ID`.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
X-Request-ID: {{requestId}}
```

Wird der Header gesendet, gibt die API die ID unverändert zurück. Fehlt er, erzeugt JobHandy eine ID und liefert sie in der Response.

## Zweck

Eine Request-ID verknüpft:

* den Client-Versuch
* die API-Response
* Kundenlogs und Metriken
* JobHandy-Diagnosedaten
* einen Supportfall

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant Scheduler
    participant Client
    participant API as JobHandy API
    participant Logs

    Scheduler->>Client: Logische Operation starten
    Client->>Client: UUID für Versuch 1 erzeugen
    Client->>API: Anfrage + X-Request-ID
    API-->>Client: Response + dieselbe X-Request-ID
    Client->>Logs: Operation, Status, Fehlercode und Request-ID speichern
```

## Validierung

Der Wert muss eine UUID v4 oder v7 sein. Ungültige Werte schlagen mit `INVALID_REQUEST_ID` fehl.

## Ein Versuch, eine Request-ID

Erzeugen Sie für jeden HTTP-Versuch eine neue Request-ID. Verknüpfen Sie Retries in Ihrer eigenen Telemetrie über eine interne ID der logischen Operation.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
logicalOperationId: order-69eb125feddfff1d13676751-approval
attempt 1 requestId: <generierte UUID v4/v7>
attempt 2 requestId: <neue generierte UUID v4/v7>
```

## Kein Idempotency Key

`X-Request-ID`:

* dedupliziert keine Anfragen
* garantiert keine Exactly-once-Ausführung
* macht `POST`- oder Statusübergangs-Anfragen nicht sicher wiederholbar
* beweist nicht, dass ein Write nach einem Timeout nicht angewendet wurde

Lesen Sie nach einem mehrdeutigen Ergebnis eines Schreibvorgangs die betroffene Ressource erneut, bevor Sie entscheiden, ob ein weiterer Schreibvorgang erforderlich ist.

## Logging-Empfehlung

Protokollieren Sie:

* UTC-Zeitstempel
* Methode und Pfadtemplate
* Tenant-Kontext
* HTTP-Status
* API-Fehlercode
* Request-ID
* Nummer des Retry-Versuchs
* interne ID der logischen Operation

Protokollieren Sie weder den API-Key noch unnötige personenbezogene Payload-Daten.