Retries, Idempotenz und mehrdeutige Ergebnisse

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

Retry-Entscheidung

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

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

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.

Erste Schritte

Architektur & Konzepte

Integrationsleitfäden

Betrieb

Retries, Idempotenz und mehrdeutige Ergebnisse

Retry-Entscheidung

Retry-Matrix

Backoff-Beispiel

Reconciliation-Muster

Mitarbeiter erstellen

Bestellentscheidung

Patch

Betriebsregel

​Retry-Entscheidung

​Retry-Matrix

​Backoff-Beispiel

​Reconciliation-Muster

​Mitarbeiter erstellen

​Bestellentscheidung

​Patch

​Betriebsregel

Retry-Entscheidung

Retry-Matrix

Backoff-Beispiel

Reconciliation-Muster

Mitarbeiter erstellen

Bestellentscheidung

Patch

Betriebsregel