#Wiederholungen ohne Doppel
Auf dieser Seite
Netze sind unzuverlässig: ein Aufruf läuft in einen Zeitüberlauf, und Ihr System weiß nicht, ob der Auftrag angelegt wurde. Die sichere Antwort ist, denselben Aufruf zu wiederholen — und dafür muss LOGICAR ihn wiedererkennen.
#Der Schlüssel
POST /orders nimmt einen Idempotency-Key im Kopf: eine beliebige Kennung bis 200 Zeichen, am besten eine UUID, die Ihr System je Vorgang einmal erzeugt und bei jeder Wiederholung mitschickt.
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000Ohne diesen Kopf gilt Ihre externalOrderId als Schlüssel — passend für Systeme wie SAP, die mit Belegnummern arbeiten. Ohne beides gibt es keine Wiedererkennung.
#Was bei einer Wiederholung passiert
| Lage | Antwort |
|---|---|
| Derselbe Schlüssel, derselbe Inhalt | Die erste Antwort noch einmal — gleicher Status, gleicher Inhalt, mit dem Kopf Idempotent-Replayed: true. Es entsteht nichts Neues. |
| Derselbe Schlüssel, anderer Inhalt | 409 IDEMPOTENCY_KEY_REUSED. Ein Schlüssel gehört zu genau einem Vorgang. |
| Der erste Aufruf läuft noch | 409 IDEMPOTENCY_REQUEST_IN_PROGRESS mit Retry-After — kurz warten, dann bekommen Sie dessen Antwort. |
Der erste Aufruf wurde abgewiesen (400, 409, 422) oder scheiterte (5xx) | Der Schlüssel ist wieder frei: korrigiert dürfen Sie denselben Vorgang mit demselben Schlüssel noch einmal schicken. |
„Derselbe Inhalt“ heißt: dieselben Felder mit denselben Werten an denselben Endpunkt; auf die Reihenfolge der Felder im JSON kommt es nicht an. Ein Schlüssel gilt je Konto und je Umgebung — ein Testzugang kommt einem Live-Zugang nie in die Quere. Verwenden Sie für jeden Vorgang einen neuen.
Gemerkt wird ein Schlüssel 24 Stunden. Danach schützt weiter die externalOrderId: ein zweiter Auftrag mit derselben Nummer ist nicht möglich, die Antwort ist 409 EXTERNAL_ORDER_ID_EXISTS mit der Kennung des vorhandenen in details.
#Ändern und Stornieren
PATCH /orders/{id} und POST /orders/{id}/cancel sind von sich aus wiederholbar: dieselbe Änderung zweimal ergibt denselben Stand, zweimal stornieren ergibt einmal storniert. Einen Schlüssel brauchen sie nicht.
#Wann wiederholen
| Antwort | Wiederholen? |
|---|---|
| Netzwerkfehler, Zeitüberlauf | Ja, mit demselben Schlüssel. |
409 IDEMPOTENCY_REQUEST_IN_PROGRESS, 429 RATE_LIMITED | Ja, nach Retry-After Sekunden. |
500, 502, 503, 504 | Ja, mit wachsender Pause: etwa 1 s, 5 s, 30 s, 2 min. |
Übrige 4xx | Nein — erst die Ursache beheben. |
Achtung
Ohne Idempotency-Key und ohne externalOrderId gibt es keine Wiedererkennung. Das ist erlaubt, heißt aber: zwei Aufrufe sind zwei Aufträge.