Idempotente Operationen und sichere Wiederholungen entwerfen

Ziel

Ein Client, dessen Anfrage in einem Timeout endet, soll sie gefahrlos wiederholen können: keine doppelte Bestellung, keine doppelte Zahlung, kein doppelter Artikel.

Voraussetzungen

RFC 9110 nennt eine Methode idempotent, wenn die beabsichtigte Wirkung mehrerer identischer Anfragen auf dem Server dieselbe ist wie die einer einzigen; PUT, DELETE und die sicheren Methoden (GET, HEAD, OPTIONS, TRACE) sind es, POST nicht. Dieselbe RFC hält fest, dass ein Client eine Anfrage mit nicht-idempotenter Methode nicht automatisch wiederholen soll, sofern er nicht weiss, dass die Semantik tatsächlich idempotent ist. Für POST beschreibt der IETF-Entwurf «The Idempotency-Key HTTP Header Field» (Arbeitsgruppe HTTPAPI; Version 07 vom Oktober 2025, Stand September 2026 abgelaufen und nicht als RFC veröffentlicht) den Header, den Stripe und andere Anbieter einsetzen. Nötig sind ein Speicher für einen kleinen Datensatz pro Schlüssel und Clients, die pro logischer Operation einen eindeutigen Schlüssel erzeugen.

Schritte

1. Methoden nach RFC 9110 wählen: Ändern per PUT auf eine bekannte Adresse, Löschen per DELETE; beide dürfen ohne Zusatzmechanik wiederholt werden.
2. Für erzeugende POST-Anfragen einen Idempotency-Key-Header annehmen. Der Entwurf empfiehlt eine UUID oder eine vergleichbar zufällige Kennung; Stripe schlägt V4-UUIDs vor, erlaubt bis zu 255 Zeichen und rät von sensiblen Daten als Schlüssel ab.
3. Beim ersten Eintreffen den Schlüssel zusammen mit einem Fingerabdruck der Anfrage (Hash über Pfad und Körper), dem Konto und dem Ergebnis (Status, Antwortkörper) speichern – in derselben Transaktion wie die Operation selbst oder unter einer Sperre auf den Schlüssel, damit zwei gleichzeitige Wiederholungen nicht beide durchkommen.
4. Bei erneutem Schlüssel mit gleichem Fingerabdruck die gespeicherte Antwort unverändert zurückgeben. Bei gleichem Schlüssel und anderem Körper 422 antworten, wie der Entwurf es vorsieht; ist die ursprüngliche Anfrage noch in Arbeit, 409.
5. Schlüssel nach einer dokumentierten Frist löschen; Stripe beschreibt eine Entfernung nach frühestens 24 Stunden und behandelt einen danach wiederverwendeten Schlüssel als neue Anfrage.
6. Schlüsselformat, Frist und Konfliktverhalten in der API-Dokumentation festhalten, damit Clients und Agenten sich darauf verlassen können, statt zu raten.

Erwartetes Ergebnis

Ein Client, der nach einem Timeout mit demselben Schlüssel wiederholt, erhält genau eine erzeugte Ressource und zweimal dieselbe Antwort.

Grenzen und Prüfbasis

Idempotenz deckt den Zustand des eigenen Servers ab, nicht Nebenwirkungen in fremden Systemen (eine zweimal verschickte E-Mail eines nachgelagerten Dienstes). Schlüssel gehören pro Konto getrennt, sonst kollidieren Clients. Der Entwurf ist keine RFC und derzeit abgelaufen; Aussagen zu Header und Statuscodes folgen dem Entwurf und der zitierten Stripe-Dokumentation, eine Messung wird nicht behauptet.