Bestellungen sicher wiederholen

Schlägt POST /api/orders wegen eines Timeouts oder Netzfehlers fehl, weißt du nicht, ob die Bestellung angelegt wurde. Ohne weitere Maßnahme würde ein Wiederholen eine zweite Bestellung erzeugen. Der Header Idempotency-Key verhindert das.

So funktioniert es

Schicke bei der Bestellanlage einen Schlüssel mit:

curl -X POST https://gateway.shirtee.cloud/api/orders \
  -H "Authorization: Bearer $SHIRTEE_API_KEY" \
  -H "Idempotency-Key: 6b0e4c1e-8a57-4f7b-9d6a-2f6e0f8a1c11" \
  -H "Content-Type: application/json" \
  -d @order.json

Wiederholung mit …	Ergebnis
gleichem Schlüssel und gleichem Inhalt	Du erhältst die erste Bestellung zurück (`201`), es entsteht keine zweite.
gleichem Schlüssel und anderem Inhalt	`422` mit `extra.error` = `IDEMPOTENCY_KEY_REUSED`. Es entsteht nichts.
ohne Schlüssel	Jeder Aufruf legt eine neue Bestellung an.

Regeln für den Schlüssel

1 bis 128 sichtbare ASCII-Zeichen. Eine UUID eignet sich gut.
Er gilt nur für dein Konto. Zwei Händler können denselben Wert verwenden, ohne sich zu stören.
Er bleibt an die angelegte Bestellung gebunden. Der Code kennt keine Ablaufzeit.
Gleichzeitige Anfragen mit demselben Schlüssel legen die Bestellung nur einmal an.

Empfohlener Ablauf

Erzeuge pro Bestellung einmal einen Schlüssel und speichere ihn bei deiner Bestellung, bevor du sendest.
Wiederhole bei Timeout, Netzfehler oder 5xx mit demselben Schlüssel und demselben Inhalt.
Erzeuge nur dann einen neuen Schlüssel, wenn du bewusst eine neue Bestellung willst.