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

# Retries, Idempotenz und mehrdeutige Ergebnisse

> Wiederholen Sie Anfragen nur, wenn ein Replay sicher ist, und gleichen Sie Write-Timeouts durch Lesen des aktuellen Ressourcenstatus ab.

Der öffentliche v1-Vertrag definiert keinen allgemeinen Idempotency-Key-Header. `X-Request-ID` dient ausschließlich der Korrelation.

## Retry-Entscheidung

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart TD
    A[Anfrage fehlgeschlagen oder Timeout] --> B{Read oder Write?}
    B -- Read --> C{Transienter Status oder Netzwerkfehler?}
    C -- Ja --> D[Mit begrenztem Backoff wiederholen]
    C -- Nein --> E[Anfrage korrigieren oder stoppen]

    B -- Write --> F{Beweist die Response, dass kein Write erfolgte?}
    F -- Ja --> G[Anfrage korrigieren oder bei sicherem Replay wiederholen]
    F -- Nein / unbekannt --> H[Betroffene Ressource erneut lesen]
    H --> I{Gewünschter Zustand bereits angewendet?}
    I -- Ja --> J[Lokal abgleichen]
    I -- Nein --> K{Replay nach Prüfung des aktuellen Zustands sicher?}
    K -- Ja --> L[Mit neuer Request-ID wiederholen]
    K -- Nein --> M[Zur manuellen Klärung eskalieren]
```

## Retry-Matrix

| Situation                                       | Automatischer Retry | Erforderliches Verhalten                                                    |
| ----------------------------------------------- | ------------------: | --------------------------------------------------------------------------- |
| `GET`-Timeout oder transienter 5xx              | In der Regel sicher | Begrenztes exponentielles Backoff und Retry-Budget verwenden                |
| `429`                                           |        Ja, begrenzt | `Retry-After` vor dem nächsten Versuch berücksichtigen                      |
| `400`, `401`, `403`, `406`, `413`, `415`, `422` |                Nein | Anfrage, Zugangsdaten, Scope, Medientyp oder Daten korrigieren              |
| `409`                                           |  Kein blinder Retry | Aktuelle Ressource erneut lesen und Konflikt auflösen                       |
| Timeout bei Create                              |  Kein blinder Retry | Vor erneutem Create suchen oder abgleichen                                  |
| Timeout bei Bestellentscheidung                 |  Kein blinder Retry | Bestellung erneut lesen und aktuellen Status vergleichen                    |
| Timeout bei Patch                               |  Kein blinder Retry | Ressourcenfelder erneut lesen, bevor ein weiterer Patch gesendet wird       |
| Timeout beim Attachment-Upload                  |  Kein blinder Retry | Incident-Status und, sofern verfügbar, Attachment-Ergebnis erneut prüfen    |
| Binärer Download mit `502`/`503`/`504`          |             Bedingt | Download mit Backoff wiederholen; Teildaten nicht als vollständig behandeln |

## Backoff-Beispiel

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
attempt 1: sofort
attempt 2: 1 Sekunde + Jitter
attempt 3: 2 Sekunden + Jitter
attempt 4: 4 Sekunden + Jitter
stoppen, sobald das Retry-Budget ausgeschöpft ist
```

Verwenden Sie bei `429` den Wert von `Retry-After` als Mindestwartezeit.

## Reconciliation-Muster

### Mitarbeiter erstellen

* Speichern Sie einen stabilen Quellidentifikator wie `employeeNumber`.
* Suchen Sie nach einem Timeout anhand dieses stabilen Quellidentifikators, bevor Sie erneut erstellen.
* Behandeln Sie eine Duplicate-Response als Signal zur Reconciliation, nicht als transienten Fehler.

### Bestellentscheidung

* Lesen Sie die Bestellung unmittelbar vor der Entscheidung.
* Lesen Sie sie nach einem Timeout erneut.
* Wenn der Status die Entscheidung bereits widerspiegelt, erfassen Sie den Vorgang lokal als erfolgreich.
* Wenn die Bestellung weiterhin entscheidbar ist, prüfen Sie, ob ein kontrolliertes Replay angemessen ist.

### Patch

* Lesen Sie die aktuelle Ressource.
* Vergleichen Sie die von der Integration verantworteten Felder.
* Patchen Sie nur Felder, die weiterhin abweichen.

## Betriebsregel

<Warning>
  Wiederholen Sie einen Schreibvorgang niemals allein deshalb, weil der Client keine Erfolgsantwort erhalten hat. Ein Netzwerk-Timeout kann auftreten, nachdem JobHandy die Änderung bereits gespeichert hat.
</Warning>