Idempotenz und Retries über Proxys: Wie ein wiederholter Request keine doppelte Bestellung erzeugt
Inhalt des Artikels
- Einleitung: ein klick, zwei bestellungen und ein tunnel, in dem antworten verloren gehen
- Grundlagen: was idempotenz ist und warum eine request-wiederholung überhaupt gefährlich ist
- Tiefeneinstieg: der serverseitige vertrag und die anatomie einer sicheren wiederholung
- Methode 1: idempotenz-key auf client-seite erzeugen und übergeben
- Methode 2: serverseitige implementierung des key-speichers
- Methode 3: retry-protokoll über den proxy, das die idempotenz nicht bricht
- Methode 4: wenn der server keine idempotenz-keys unterstützt
- Typische fehler: wie teams selbst duplikate erzeugen
- Werkzeuge und ressourcen für die implementierung
- Fälle und ergebnisse
- Faq: schwierige fragen zu idempotenz und wiederholungen
- Fazit: vertrag statt hoffnung
Einleitung: ein Klick, zwei Bestellungen und ein Tunnel, in dem Antworten verloren gehen
Stellen Sie sich eine Integration vor, die seit Jahren läuft. Ihr Dienst schickt Bestellungen an ein externes System, der Verkehr läuft über einen Pool mobiler Proxys, um Anfragen nach Regionen zu verteilen und nicht an die Limits einer einzelnen Adresse zu stoßen. Alles stabil. Und plötzlich kommt die Buchhaltung mit einem Bericht: Im Laufe eines Monats sind beim Partner siebenundvierzig Zwillingsbestellungen aufgetaucht. Gleiche Waren, gleiche Beträge, Erstellungszeitpunkt drei bis vier Sekunden auseinander. Niemand hat etwas geändert. Was ist passiert?
Das ganz Normale ist passiert: Die Verbindung durch den Proxy brach auf dem Rückweg ab. Der Server hat die Anfrage erhalten, die Bestellung angelegt, die Antwort geschickt – aber die Antwort hat den Client nie erreicht. Der Client dachte ehrlich, die Anfrage sei fehlgeschlagen, und hat sie wiederholt. Auch die zweite Anfrage wurde ausgeführt. So entsteht ein Duplikat, und keine Retry-Policy schützt von sich aus davor.
Hier ist es wichtig, sofort eine Grenze zu ziehen. Wie man Anfragen nach einem 429-Fehler korrekt wiederholt, wie lange man zwischen Versuchen wartet und wie man exponentielle Verzögerungen aufbaut, haben wir an anderer Stelle beschrieben: Das ist das Thema der Retry-Policy. Heute geht es um etwas anderes. Wir sprechen über den Vertrag zwischen Client und Server, der eine Wiederholung sicher oder gefährlich macht, unabhängig davon, wie genau Sie sie ausführen. Dieser Vertrag heißt Idempotenz, und sein wichtigstes Werkzeug ist der Idempotenz-Key.
Warum ist das Thema gerade bei der Arbeit über Proxys so brisant? Weil der Proxy der Kette einen weiteren Abschnitt hinzufügt, in dem die Antwort verloren gehen kann. Mobile Proxys ändern zusätzlich die externe IP bei der Rotation, und der Server kann die zweite Anfrage durchaus von einer anderen Adresse sehen. Wenn Ihr Schutz vor Duplikaten auf Session, IP oder einem Zeitfenster beruht, zerfällt er. Wenn er auf einem Idempotenz-Key beruht, ist es ihm egal, woher die Wiederholung kommt.
In diesem Leitfaden erfahren Sie, wie Idempotenz auf Protokoll- und Business-Logik-Ebene funktioniert, wie man Keys erzeugt und speichert, wie man einen serverseitigen Speicher entwirft, der konkurrierenden Wiederholungen standhält, was man tut, wenn eine externe API keine Keys unterstützt, und an welchen Fehlern selbst erfahrene Teams stolpern. Wir schauen uns Fälle mit Zahlen an, sammeln Checklisten und beantworten unbequeme Fragen. Der Artikel richtet sich an Integrationsentwickler, Architekten und technische Leads, die mit Bestellungen, Zahlungen und allen Vorgängen arbeiten, bei denen „zweimal“ „schlecht“ bedeutet.
Grundlagen: Was Idempotenz ist und warum eine Request-Wiederholung überhaupt gefährlich ist
Definition in einfachen Worten
Eine Operation heißt idempotent, wenn ihre mehrfache Ausführung dasselbe Ergebnis liefert wie ihre einmalige Ausführung. Zehnmal den Aufzugsknopf drücken ist idempotent: Der Aufzug kommt einmal. Noch eine Einheit eines Artikels in den Warenkorb legen ist nicht idempotent: Jeder Klick ändert den Zustand. Geld überweisen ist definitiv nicht idempotent, es sei denn, das System ist speziell so entworfen, dass eine Wiederholung der Überweisung mit derselben Kennung nichts tut.
In HTTP gibt es Methoden, die laut Spezifikation als idempotent gelten: GET, PUT, DELETE, HEAD. Es gibt die Methode POST, die standardmäßig nicht als idempotent gilt. Genau POST wird am häufigsten zum Anlegen von Bestellungen, Zahlungen und zum Versenden von Nachrichten verwendet. Das heißt, die riskanteste Operation lebt in der am wenigsten idempotenten Methode. Zufall? Eher eine historische Gesetzmäßigkeit, mit der man arbeiten muss.
Drei Ausgänge jeder Anfrage
Wenn der Client eine Anfrage sendet und keine Antwort erhält, befindet er sich in einem Zustand der Ungewissheit. Es gibt genau drei Szenarien:
- Die Anfrage hat den Server nicht erreicht. Wiederholen ist sicher: Es ist nichts passiert.
- Die Anfrage ist angekommen, der Server hat die Operation ausgeführt, die Antwort ging verloren. Wiederholen ist gefährlich: Die Operation wird ein zweites Mal ausgeführt.
- Die Anfrage ist angekommen, der Server hat mit der Ausführung begonnen und noch nicht abgeschlossen. Wiederholen ist doppelt gefährlich: Zwei Operationen werden parallel ausgeführt.
Das Kernproblem ist, dass der Client diese Szenarien nicht unterscheiden kann. Ein Timeout sieht in allen drei Fällen gleich aus. Eine unterbrochene Verbindung ebenso. Daraus folgt ein grundlegendes Prinzip verteilter Systeme: Zuverlässige Zustellung ist nur als „mindestens einmal“ (at-least-once) möglich. Die Garantie „genau einmal“ (exactly-once) lässt sich auf Transportebene nicht erreichen; man kann sie nur auf Anwendungsebene emulieren, indem man Wiederholungen harmlos macht. Idempotenz ist genau diese Art der Emulation.
Wie der Proxy die Kette der Ungewissheit verlängert
Ohne Proxy gibt es zwischen Client und Server einen Netzwerkabschnitt. Mit Proxy sind es zwei: Client – Proxy und Proxy – Server. Die Antwort kann auf jedem von beiden verloren gehen. Und wenn sie auf dem ersten Abschnitt verloren geht, hat der Proxy die Antwort bereits erhalten, der Server die Operation bereits abgeschlossen, und der Client wird es nie erfahren.
Mobile Proxys bringen ihre eigene Besonderheit mit. Bei ihnen gibt es IP-Rotation nach Zeitplan oder auf Anfrage, Wechsel zwischen Basisstationen, natürliche Schwankungen der Funkkanalqualität. Jedes dieser Ereignisse kann die TCP-Verbindung zu einem beliebigen Zeitpunkt unterbrechen. Und meistens bricht die Verbindung nicht während der Übertragung des Request-Bodys ab (er ist klein und fliegt schnell raus), sondern während des Wartens auf die Antwort, wenn die Verbindung einfach offen gehalten wird. Genau in diesem Moment verarbeitet der Server Ihre Bestellung. Genau in diesem Moment bietet ein Abbruch die größte Chance auf ein Duplikat.
Was ein Idempotenz-Key ist
Der Idempotenz-Key (Idempotency-Key) ist eine eindeutige Kennung eines Geschäftsvorgangs, die der Client einmal erzeugt und mit jedem Versuch, diesen Vorgang auszuführen, mitsendet. Der Server merkt sich den Key und das Ergebnis. Bei einer erneuten Anfrage mit demselben Key führt der Server die Operation nicht erneut aus, sondern liefert das gespeicherte Ergebnis zurück. Der Client kann beliebig oft wiederholen: Die Bestellung wird einmal angelegt.
Achten Sie auf die Formulierung: Der Key identifiziert den Vorgang, nicht die HTTP-Anfrage. Dieser Unterschied wird später zentral, wenn wir Implementierungsfehler besprechen.
Tiefeneinstieg: der serverseitige Vertrag und die Anatomie einer sicheren Wiederholung
Der Vertrag als Verhaltensvereinbarung
Idempotenz ist kein Header und keine Bibliothek. Sie ist ein Vertrag, in dem der Server dem Client ein konkretes Verhalten bei Wiederholungen verspricht und der Client sich an die Regeln zur Schlüsselerzeugung hält. Ein guter Vertrag beantwortet die folgenden Fragen:
- Welche Entität ist die Einheit der Idempotenz: Bestellung, Zahlung, Bestellposition, Batch?
- Wie übergibt der Client den Key: Header, Body-Feld, Teil der URL?
- Was passiert, wenn der Key übereinstimmt, aber der Request-Body anders ist?
- Was passiert, wenn die erste Anfrage noch läuft und eine zweite mit demselben Key eintrifft?
- Wie lange erinnert sich der Server an den Key?
- Was wird bei einer Wiederholung zurückgegeben: exakt dieselbe Antwort Byte für Byte oder der aktuelle Zustand der Entität?
- Wie unterscheidet sich eine Wiederholung in Logs und Metriken von einer neuen Anfrage?
Wenn auch nur eine dieser Fragen in der API-Dokumentation unbeantwortet bleibt, ist der Vertrag unvollständig, und in unklaren Situationen hängt das Verhalten von der Implementierung, der Version und der Mondphase ab.
Drei Zustände eines Keys
Auf dem Server durchläuft jeder Key einen Lebenszyklus aus drei Zuständen. Das Verständnis dieses Zyklus erklärt neunzig Prozent der Duplikatprobleme.
- Nicht vorhanden. Der Key wird zum ersten Mal gesehen. Der Server muss ihn atomar reservieren und mit der Verarbeitung beginnen.
- In Bearbeitung (in-progress). Die erste Anfrage wird verarbeitet. Eine zweite Anfrage mit demselben Key darf keine zweite Verarbeitung starten. Optionen: 409 Conflict mit der Aufforderung zu warten zurückgeben, bis zur Beendigung der ersten blockieren und deren Ergebnis zurückgeben, 202 Accepted mit Link zum Status zurückgeben.
- Abgeschlossen. Das Ergebnis ist gespeichert. Eine Wiederholung liefert das gespeicherte Ergebnis ohne Nebenwirkungen zurück.
Der häufigste Architekturfehler ist das Überspringen des mittleren Zustands. Der Entwickler prüft „ist der Key in der Datenbank“, findet nichts, beginnt mit der Verarbeitung, und eine parallele Wiederholung tut im selben Moment dasselbe. Zwei Threads, zwei Prüfungen, zwei Bestellungen. Prüfung und Reservierung müssen eine einzige atomare Operation sein: ein Insert mit Unique-Index, ein bedingtes Schreiben in Redis, eine Transaktion mit Sperre.
Der Request-Fingerprint
Der Key identifiziert den Vorgang, aber einen Vorgang mit welchem Inhalt? Wenn der Client wegen eines Bugs den Key K mit dem Betrag 1000 Rubel geschickt hat und dann mit demselben Key und dem Betrag 10000 wiederholt, was soll der Server tun? Das Ergebnis der ersten Operation still zurückgeben ist gefährlich: Der Client glaubt, er habe 10000 bezahlt. Die zweite ausführen verletzt die Idempotenz.
Die richtige Antwort: Der Server speichert einen Fingerprint der Anfrage – einen Hash des normalisierten Bodys und der relevanten Header. Bei einer Wiederholung mit demselben Key, aber einem anderen Fingerprint wird ein Fehler 422 Unprocessable Content oder 400 mit einem expliziten Code wie idempotency_key_reused_with_different_payload zurückgegeben. Das schützt vor logischen Fehlern des Clients und vor gefälschten Wiederholungen.
Antwortspeicherung: Snapshot oder aktueller Zustand
Es gibt zwei Ansätze dafür, was bei einer Wiederholung zurückgegeben wird. Snapshot – der Server speichert Status, Header und Body der ursprünglichen Antwort und gibt sie unverändert zurück. Das ist streng idempotent und vorhersehbar. Aktueller Zustand – der Server findet anhand des Keys die erstellte Entität und gibt deren aktuelle Darstellung zurück. Das ist bequemer, wenn die Bestellung zwischen den Versuchen in einen anderen Status übergegangen ist, aber weniger vorhersehbar.
In Zahlungssystemen dominiert der Snapshot: Der Client muss genau die Antwort erhalten, die es beim ersten Versuch gab. In Bestellverwaltungssystemen wird oft ein Hybrid verwendet: Snapshot für Fehlercodes, aktueller Zustand für den Erfolg. Wichtig ist nur, dass die Wahl im Vertrag festgehalten wird.
Was der Proxy auf Vertragsebene ändert
Technisch ist der Proxy nicht am Idempotenz-Vertrag beteiligt: Er ist transparent für Header und Body. Aber er verändert die Wahrscheinlichkeiten. Über eine direkte Verbindung ist der Verlust einer Antwort bei erfolgreicher Ausführung eine Seltenheit, ein Bruchteil eines Prozents. Über eine Kette mit mobilem Proxy und Rotation wird dieses Ereignis regelmäßig. Wir haben Integrationen beobachtet, bei denen bei einer IP-Rotation alle fünf Minuten etwa 0,3–0,8% der Anfragen mit einem Verbindungsabbruch in der Phase des Wartens auf die Antwort endeten. Bei zehntausend Bestellungen pro Tag sind das täglich dreißig bis achtzig potenzielle Duplikate. Ohne Idempotenz-Key wird jedes davon zu einem echten Duplikat.
Es gibt noch eine zweite Feinheit. Viele Server bauen in ihre Anti-Fraud-Logik die Prüfung ein: „wiederholte Anfrage von einer anderen IP“. Bei der Rotation eines mobilen Proxys kommt die Wiederholung fast immer von einer neuen Adresse. Wenn der Server das als verdächtige Aktivität deutet und die Wiederholung ablehnt, ohne den Key-Speicher zu konsultieren, erhält der Client nicht das gespeicherte Ergebnis und bleibt in Ungewissheit. Ein guter Vertrag prüft den Key vor allen netzwerkgebundenen Heuristiken.
Methode 1: Idempotenz-Key auf Client-Seite erzeugen und übergeben
Wo der Key entsteht
Die wichtigste Regel: Der Key wird einmal pro Geschäftsvorgang erzeugt, vor dem ersten Sendeversuch, und zusammen mit der Absicht, den Vorgang auszuführen, gespeichert. Wenn der Key innerhalb des HTTP-Clients bei jedem Aufruf neu erzeugt wird, bekommt der Retry einen neuen Key, und der gesamte Schutz ist hinfällig. Das ist ein so häufiger Fehler, dass wir ihn separat im Abschnitt über Anti-Patterns aufführen, aber hier wiederholen: Der Key lebt auf der Ebene des Bestellservices, nicht auf der Transportebene.
Die praktische Reihenfolge sieht so aus:
- Der Nutzer oder ein interner Prozess initiiert die Bestellerstellung.
- Der Dienst legt einen lokalen Datensatz „Bestellabsicht“ mit Status pending an und erzeugt den Key.
- Key und Nutzlast werden in einer Transaktion in der lokalen Datenbank gespeichert.
- Erst nach dem Commit der Transaktion wird der Versand an die externe API über den Proxy gestartet.
- Alle Wiederholungen lesen den Key aus dem lokalen Datensatz, statt einen neuen zu erzeugen.
- Nach Erhalt der Antwort wird der lokale Datensatz mit dem Ergebnis und der externen Bestell-ID aktualisiert.
Diese Reihenfolge garantiert, dass selbst ein Neustart Ihres Dienstes mitten in den Wiederholungen nicht zu einem Key-Wechsel führt: Er liegt in der Datenbank.
Format des Keys
Der Key muss global eindeutig und für Dritte unvorhersehbar sein. Bewährte Varianten:
- UUID Version 4 – der Klassiker, 122 Bit Zufall, überall geeignet.
- UUID Version 7 oder ULID – enthalten einen Zeitstempel in den höherwertigen Bits, was sie für Sortierung und Indizierung in der Server-Datenbank praktisch macht. Im Jahr 2026 sind sie bereits die Standardwahl für neue Systeme.
- Deterministischer Key aus einer natürlichen Kennung – zum Beispiel ein Hash aus Warenkorb-ID, Nutzer-ID und Warenkorbversion. Nützlich, wenn der Client seinen Zustand verlieren und den Key aus denselben Daten neu erzeugen kann.
Was man vermeiden sollte: fortlaufende Nummern (leicht zu erraten, um an die Antwort eines anderen zu gelangen), kurze Strings, Keys, die nur von der Zeit mit geringer Auflösung abhängen.
Art der Übergabe
Der De-facto-Standard ist der Header Idempotency-Key. Der IETF-Spezifikationsentwurf legt genau diesen Namen fest, und die meisten modernen APIs halten sich daran. Beispielaufruf über einen Proxy:
curl -x http://user:pass@proxy.example:8080 -H "Idempotency-Key: 018f3a2c-7b1e-7c3d-9a4e-1f2b3c4d5e6f" -H "Content-Type: application/json" -d '{"cart_id":"c-9921","amount":149000}' https://api.partner.example/v1/orders
Manche APIs akzeptieren den Key im Request-Body (Feld client_reference_id, external_id, request_id). Das ist ebenfalls eine funktionierende Variante, aber mit einer Feinheit: Wenn der Server das Body-Feld als Key verwendet, muss es zwingend in einen Unique-Index einfließen, sonst ist es nur eine Markierung und kein Schutz.
Geltungsbereich des Keys
Der Key muss innerhalb eines Client-Kontos und eines Endpunkts eindeutig sein. Ein guter Server bildet den internen Speicherschlüssel als Kombination aus Konto-ID, Methode, Pfad und übergebenem Key. Das schützt vor Kollisionen zwischen verschiedenen Clients und vor versehentlicher Wiederverwendung eines Keys für einen anderen Vorgang.
Checkliste für die Client-Seite
- Der Key wird vor dem ersten Versuch erzeugt und zusammen mit der Absicht in der Datenbank gespeichert.
- Alle Wiederholungen verwenden denselben Key.
- Der Request-Body stimmt bei der Wiederholung Byte für Byte mit dem ersten Versuch überein.
- Der Client kann 409 (Vorgang in Bearbeitung) als Signal zum Warten und erneuten Versuchen behandeln, nicht als Fehler.
- Der Client kann 422 mit dem Code für abweichenden Fingerprint als logischen Fehler behandeln, der Eingreifen erfordert.
- Der Client protokolliert den Key in allen Einträgen, die mit dem Vorgang zusammenhängen, damit Duplikate untersucht werden können.
- Der Client verwirft den Key nicht beim Proxy-Wechsel, bei der IP-Rotation oder beim Umschalten auf einen Reservpool.
Methode 2: Serverseitige Implementierung des Key-Speichers
Wenn Sie der Eigentümer des Servers sind, den Ihre Clients oder Partner über einen Proxy ansprechen, ist dieser Abschnitt für Sie. Wenn Sie nur Client sind, hilft er Ihnen, die Qualität einer fremden Implementierung anhand der Dokumentation und des Verhaltens einzuschätzen.
Speicherschema
Die minimale Tabelle oder Struktur für Keys enthält folgende Felder:
- scope_key – zusammengesetzter Schlüssel: Konto, Methode, Pfad, übergebener Idempotency-Key. Unique-Index.
- fingerprint – Hash des normalisierten Request-Bodys.
- state – einer der Werte: in_progress, completed, failed.
- response_status, response_headers, response_body – Snapshot der Antwort, wird bei Abschluss gefüllt.
- resource_id – Kennung der erstellten Entität, falls zutreffend.
- locked_at, completed_at, expires_at – Zeitstempel für die Behandlung hängender Vorgänge und die Bereinigung.
Atomare Reservierung
Das Herz der Implementierung ist die Operation, die mit einer einzigen Aktion entweder einen Datensatz im Zustand in_progress anlegt oder meldet, dass bereits einer existiert. In einer relationalen Datenbank ist das ein Insert mit Konfliktbehandlung über einen Unique-Index. In Redis ist es der Befehl SET mit den Flags NX und EX, der den Wert nur schreibt, wenn der Key fehlt, und sofort eine Lebensdauer setzt. Kein „erst SELECT, dann INSERT“: Dazwischen schlüpft eine parallele Wiederholung durch.
Pseudocode auf Logikebene:
- scope_key und fingerprint berechnen.
- Versuchen, einen Datensatz mit state = in_progress einzufügen. Wenn das Insert gelingt, zur Ausführung des Vorgangs übergehen.
- Bei Konflikt: den vorhandenen Datensatz lesen.
- Wenn der Fingerprint nicht übereinstimmt – 422 mit dem Code für Nichtübereinstimmung zurückgeben.
- Wenn state = in_progress – 409 mit Header Retry-After zurückgeben oder auf den Abschluss warten (innerhalb eines vernünftigen Timeouts).
- Wenn state = completed – den gespeicherten Antwort-Snapshot mit einem Header zurückgeben, der die Wiederholung markiert, zum Beispiel
Idempotent-Replayed: true.
Ausführung und Festschreibung des Ergebnisses
Hier lauert die zweite Falle. Der Vorgang wurde ausgeführt, die Bestellung angelegt, aber der Prozess ist abgestürzt, bevor das Ergebnis im Key-Speicher geschrieben wurde. Der Datensatz bleibt für immer im Zustand in_progress. Eine Wiederholung erhält 409, dann noch 409, und so weiter bis in alle Ewigkeit.
Es gibt drei Lösungsansätze:
- Eine einzige Transaktion. Das Anlegen der Bestellung und das Aktualisieren des Key-Datensatzes laufen in einer Datenbanktransaktion. Die zuverlässigste Variante, wenn Bestellung und Keys in derselben Datenbank leben.
- Key als Teil der Entität. Der Idempotenz-Key wird direkt in der Bestelltabelle mit einem Unique-Index gespeichert. Dann ist die Bestellung selbst der Key-Datensatz; eine separate Tabelle ist nicht nötig. Einfach und zuverlässig für Fälle mit einer Entität pro Vorgang.
- Wiederherstellung hängender Vorgänge. Ein Hintergrundprozess findet Datensätze im Zustand in_progress, die älter als eine Schwelle sind (zum Beispiel 60 Sekunden), prüft, ob der Vorgang tatsächlich ausgeführt wurde (anhand resource_id oder Suche nach der Entität), und schreibt entweder die Festschreibung zu Ende oder setzt den Datensatz auf failed, sodass eine Wiederholung möglich wird.
Fehlerbehandlung beim ersten Versuch
Was soll gespeichert werden, wenn der erste Versuch mit einem Fehler endet? Das hängt von der Fehlerart ab. Validierungsfehler (400, 422) sind deterministisch: Eine Wiederholung mit demselben Body liefert dasselbe Ergebnis, sie können gecacht werden. Infrastrukturfehler (500, 503, Datenbank-Timeout) sind nicht deterministisch: Wenn man sie cacht, kann der Client den Vorgang nie erfolgreich abschließen. Richtiges Verhalten: Bei einem Infrastrukturfehler den Key freigeben (den Datensatz löschen oder auf failed setzen mit der Möglichkeit der erneuten Übernahme), damit der nächste Versuch es erneut probiert.
Lebensdauer des Keys
Keys können nicht ewig gespeichert werden: Die Tabelle würde überlaufen. Aber eine zu kurze Frist ist gefährlich: Wenn der Client eine halbe Stunde nach einem Netzwerkausfall wiederholt, muss der Key noch leben. Die Praxis großer Zahlungsdienstleister einigt sich auf 24 Stunden als Minimum. Für Bestellungen im E-Commerce sind 24–72 Stunden vernünftig. Für Vorgänge, die der Client nach längeren Störungen wiederholen kann (zum Beispiel eine Katalogsynchronisierung einmal pro Tag), muss die Frist den Synchronisierungsintervall mindestens verdoppeln.
Beobachtbarkeit
Jede Wiederholung sollte eine Spur hinterlassen. Metriken, die man sammeln sollte: Anzahl der Wiederholungen mit Treffer im Zustand completed (harmlose Wiederholungen), Anzahl der 409 (konkurrierende Wiederholungen), Anzahl der 422 (Nichtübereinstimmung des Fingerprints – fast immer ein Client-Bug), Alter des ältesten Datensatzes im Zustand in_progress (Indikator für hängende Vorgänge). Das Verhältnis von Wiederholungen zu eindeutigen Vorgängen ist ein direktes Maß für die Netzwerkqualität zwischen Client und Server. Wenn es stark steigt, hat sich irgendwo die Qualität des Proxy-Kanals verschlechtert oder die Rotation geändert.
Checkliste für die Server-Seite
- Die Reservierung des Keys ist atomar.
- Es gibt einen eigenen Zustand in_progress und eine klare Antwort auf eine konkurrierende Wiederholung.
- Der Body-Fingerprint wird gespeichert, eine Nichtübereinstimmung wird mit einem expliziten Fehler abgelehnt.
- Die Festschreibung des Ergebnisses ist transaktional oder es gibt einen Mechanismus zur Wiederherstellung hängender Datensätze.
- Infrastrukturfehler werden nicht gecacht, deterministische werden gecacht.
- Die TTL beträgt mindestens 24 Stunden und ist dokumentiert.
- Eine Wiederholung wird mit einem Header markiert und ist in den Metriken sichtbar.
- Die Key-Prüfung erfolgt vor netzwerkbasierten Anti-Fraud-Heuristiken.
Methode 3: Retry-Protokoll über den Proxy, das die Idempotenz nicht bricht
Die Retry-Policy ist das Thema eines Nachbarartikels, aber es gibt eine schmale Schicht, in der sich Retry-Policy und Idempotenz überschneiden: welche Signale aus der Proxy-Kette bedeuten, dass eine Wiederholung nötig ist, und wie die Wiederholung den Vertrag nicht zerstören darf. Das schauen wir uns an.
Unterscheiden Sie Proxy-Ausfall und Upstream-Ausfall
Bei der Arbeit über einen Proxy erhält der Client Fehler aus drei Quellen, und man muss unterschiedlich auf sie reagieren:
- Fehler bei der Verbindung zum Proxy. Verbindung zum Proxy nicht möglich, Proxy hat 407 (Authentifizierung erforderlich) zurückgegeben, Proxy hat die Verbindung vor dem Senden der Anfrage geschlossen. Die Anfrage hat den Server garantiert nicht erreicht. Eine Wiederholung ist auch ohne Key sicher, mit Key aber trotzdem besser.
- Fehler des Proxys beim Zugriff auf den Upstream. Der Proxy hat 502 Bad Gateway oder 504 Gateway Timeout zurückgegeben. Hier ist die Ungewissheit maximal: 502 bedeutet normalerweise, dass der Upstream nicht korrekt geantwortet hat, aber den Vorgang ausgeführt haben könnte; 504 bedeutet, dass der Proxy das Warten satt hatte, während der Server möglicherweise noch verarbeitet. Wiederholung nur mit Key.
- Antworten des Upstreams, die den Proxy passiert haben. 500, 503, 429 vom Zielserver. Ihre Semantik wird durch den Vertrag der Ziel-API bestimmt. Wiederholung mit Key nach den Regeln der Retry-Policy.
Besondere Aufmerksamkeit verdient der Verbindungsabbruch während des Lesens der Antwort. Die Header sind bereits angekommen, der Body brach ab. Das ist der heimtückischste Fall: Den Status 201 Created haben Sie vielleicht gesehen, aber die Bestell-ID aus dem Body nicht erhalten. Eine Wiederholung mit Key liefert den vollständigen Snapshot der Antwort. Ohne Key bekommen Sie eine zweite Bestellung und erfahren trotzdem nicht die ID der ersten.
IP-Rotation als Ereignis, nicht als Hintergrund
Wenn Ihr Pool mobiler Proxys Adressen nach Zeitplan rotiert, synchronisieren Sie den Versand kritischer Vorgänge mit stabilen Fenstern. Ein einfacher Trick: bei der API des Proxy-Dienstes die Zeit bis zur nächsten Rotation abfragen und keine Bestellung anlegen, wenn bis zur Rotation weniger Zeit bleibt als Ihr Timeout für das Warten auf die Antwort. Das ersetzt keine Idempotenz, senkt aber die Zahl der Wiederholungen und damit die Last auf dem Key-Speicher und beim Anti-Fraud des Partners.
Wenn die Rotation auf Anfrage erfolgt, rufen Sie den IP-Wechsel zwischen den Versuchen eines Vorgangs nicht ohne Not auf. Manche Teams machen das „um ein Festhängen zu umgehen“, aber der Server kann beim Anblick desselben Keys von einer neuen Adresse eine zusätzliche Prüfung aktivieren. Der Key verhindert das Duplikat, aber die Wiederholung kann sich verlangsamen.
Timeouts: zwei Grenzen statt einer
Bei einer direkten Verbindung setzt man normalerweise einen Timeout für die Antwort. Über einen Proxy braucht man mindestens zwei: einen Timeout für den Verbindungsaufbau zum Proxy (kurz, Einzelsekunden) und einen Timeout für das Warten auf die Antwort des Upstreams (länger, unter Berücksichtigung der Bestellverarbeitungszeit). Wenn man sie zu einem zusammenfasst, greift der kurze Timeout ständig bei langsamer Verarbeitung und erzeugt überflüssige Wiederholungen, während der lange Sie zwingt, auf einen nicht erreichbaren Proxy unnötige Sekunden zu warten.
Wichtig: Der Timeout für das Warten auf die Antwort darf nicht kürzer sein als die tatsächliche Bestellanlegungszeit auf dem Server. Sonst brechen Sie die Verbindung systematisch genau im Moment der Verarbeitung ab, und jeder Vorgang wird zu einem Paar „abgebrochener Versuch plus Wiederholung“. Der Key bewahrt vor Duplikaten, aber der Server verbraucht Ressourcen für die Verarbeitung ins Leere.
Wiederholung über einen anderen Proxy
Eine vernünftige Strategie: Der erste Wiederholungsversuch läuft über denselben Proxy (vielleicht hat die Verbindung nur kurz gezuckt), der zweite über einen anderen Proxy aus dem Pool (vielleicht liegt das Problem am konkreten Kanal). Der Key ändert sich dabei nicht. Der Body ändert sich nicht. Nur die Route ändert sich. So trennen Sie Netzwerkprobleme von Problemen der Anfrage selbst und erhalten diagnostische Informationen: Wenn es über den zweiten Proxy sofort klappt, lag es am Kanal.
Schritt-für-Schritt-Protokoll für eine sichere Wiederholung
- Key und Body aus dem lokalen Absichtsdatensatz lesen.
- Die Anfrage über den aktuellen Proxy mit zwei Timeouts senden.
- Bei Erfolg: das Ergebnis speichern, abschließen.
- Bei 409 vom Server: die angegebene Zeit oder ein vernünftiges Intervall abwarten, mit demselben Key wiederholen.
- Bei 422 mit dem Code für abweichenden Fingerprint: stoppen, einen Incident auslösen, nicht automatisch wiederholen.
- Bei einem Verbindungsfehler zum Proxy: den Proxy wechseln, sofort wiederholen.
- Bei 502, 504, Abbruch oder Timeout: die Verzögerungsrichtlinie anwenden, mit demselben Key wiederholen; ab der zweiten Wiederholung über einen anderen Proxy.
- Nach Ausschöpfen der Versuche: den Datensatz im Zustand unknown belassen, in die Abgleich-Warteschlange übergeben (siehe Methode 4).
Punkt acht ist kritisch. Der Zustand „ich weiß nicht, ob die Bestellung angelegt wurde“ ist ein legitimer Zustand, und man darf ihn nicht stillschweigend zu „angelegt“ oder „nicht angelegt“ zusammenfalten.
Methode 4: Wenn der Server keine Idempotenz-Keys unterstützt
Die perfekte Welt endet bei der ersten Partner-API, in deren Dokumentation das Wort „Idempotenz“ fehlt. Was tun, wenn man Client ist und der Server einfach bei jedem POST eine Bestellung anlegt? Es gibt mehrere Techniken, von einfachen bis zu architektonischen.
Natürlicher Key in Request-Feldern
Viele APIs, die keinen formalen Idempotency-Key haben, akzeptieren ein Feld wie external_order_id, client_reference, merchant_order_number und versprechen Eindeutigkeit darüber innerhalb des Kontos. Das ist Idempotenz unter anderem Namen. Prüfen Sie die Dokumentation und, wichtiger, prüfen Sie das Verhalten: Senden Sie zwei Anfragen mit derselben externen ID in einer Testumgebung und schauen Sie, ob ein Duplikatfehler zurückkommt oder eine zweite Entität angelegt wird. Versprechen in der Dokumentation und tatsächliches Verhalten weichen häufiger voneinander ab, als man denkt.
Lesen vor der Wiederholung
Wenn der Server die Suche nach Entitäten anhand Ihrer externen ID oder anhand von Parametern ermöglicht (zum Beispiel eine Bestellliste mit Filter nach Zeit und Betrag), dann führen Sie vor jeder Wiederholung eine Prüfabfrage durch: Ist schon eine Bestellung mit meinen Merkmalen aufgetaucht? Das gibt keine strikte Garantie (zwischen Prüfung und Wiederholung kann ein Fenster durchrutschen), senkt aber die Duplikatwahrscheinlichkeit um eine Größenordnung. Das Schema:
- Der erste Versuch endete ungewiss.
- Ein Intervall abwarten, das ausreicht, damit die Verarbeitung auf dem Server abgeschlossen ist.
- Ein GET mit Filter nach externer ID oder einer eindeutigen Feldkombination ausführen.
- Wenn die Bestellung gefunden wird – ihre ID festhalten, eine Wiederholung ist nicht nötig.
- Wenn sie nicht gefunden wird – den POST wiederholen.
Damit die Suche funktioniert, legen Sie in der Bestellung eine Markierung an, über die man sie finden kann: Kommentar, benutzerdefiniertes Feld, eindeutige Positionsnummer. Selbst wenn der Server sie als Key ignoriert, gibt er sie in der Antwort zurück, und Sie können abgleichen.
Aufteilung des Vorgangs in Reservierung und Bestätigung
Manche APIs unterstützen ein zweiphasiges Modell: Zuerst wird ein Entwurf oder Hold angelegt (ein Vorgang, der sicher wiederholt oder storniert werden kann), dann die Bestätigung anhand der Entwurfs-ID. Die Bestätigung anhand der ID ist von Natur aus idempotent: Zweimal denselben Entwurf bestätigen geht nicht. Wenn ein solches Modell verfügbar ist, ist es dem einstufigen Anlegen vorzuziehen, selbst wenn Keys vorhanden sind, weil es das Ungewissheitsfenster des riskantesten Schritts verkleinert.
Outbox-Muster auf Ihrer Seite
Selbst wenn der Server nichts garantiert, können Sie garantieren, dass von Ihrer Seite jeder Vorgang mit genau einer Absicht hinausgeht. Transaktionale Outbox ist eine Tabelle ausgehender Vorgänge, in die ein Datensatz in derselben Transaktion wie eine Geschäftsänderung gelangt (zum Beispiel die Umstellung des Warenkorbs in den Status „wird bearbeitet“). Ein separater Sender-Prozess holt Datensätze aus der Outbox und führt die Anfragen über den Proxy aus. Jeder Datensatz hat eine eindeutige Kennung, die Sie als Key oder als external_id verwenden. Selbst bei einem Absturz des Senders mitten in der Arbeit bleibt der Datensatz in der Outbox, und die Wiederholung läuft mit derselben Kennung.
Abgleich als letzte Verteidigungslinie
Reconciliation, also der Abgleich, ist ein regelmäßiger Prozess, der die Liste Ihrer Vorgänge mit der Liste der Entitäten auf der Partnerseite vergleicht und Abweichungen findet: Bestellungen, die beim Partner existieren, aber bei Ihnen nicht verknüpft sind; Vorgänge im Zustand unknown; Duplikate mit übereinstimmenden Merkmalen. Der Abgleich verhindert kein Duplikat, aber er findet es in Minuten statt in einem Monat durch einen Buchhaltungsbericht. Für Vorgänge über instabile Kanäle ist das eine Pflichtkomponente, keine Option.
Praxis: den Abgleich alle 10–15 Minuten für Vorgänge starten, die älter sind als Ihr maximaler Retry-Timeout, gefundene Entitäten automatisch mit den Datensätzen im Zustand unknown verknüpfen und entdeckte Duplikate in eine Stornierungswarteschlange mit manueller Bestätigung übergeben, wenn der Betrag über einer Schwelle liegt.
Saga und Kompensationen
Wenn die Bestellung Teil einer Handlungskette ist (Lagerreservierung, Zahlung, Lieferung), bricht ein Duplikat in einem Glied die ganze Kette. Das Saga-Muster geht davon aus, dass es für jeden Schritt eine kompensierende Aktion gibt: Bestellstornierung, Rückerstattung, Aufhebung der Reservierung. Auch die Kompensation muss idempotent sein, sonst kämpfen Sie mit Duplikaten von Stornierungen. Entwerfen Sie die Integration so, dass Sie sofort Paare „Aktion – Kompensation“ notieren und für beide prüfen, dass eine Wiederholung sicher ist.
Typische Fehler: Wie Teams selbst Duplikate erzeugen
Fehler 1. Der Key wird im HTTP-Client erzeugt
Der häufigste. Ein Wrapper über die HTTP-Bibliothek fügt bei jedem Aufruf einen Header Idempotency-Key mit einer neuen UUID hinzu. Der Retry-Mechanismus in derselben Bibliothek ruft den Versand erneut auf – und bekommt einen neuen Key. Äußerlich sieht alles richtig aus: Der Header ist da. Tatsächlich gibt es keinen Schutz. Prüfen Sie anhand der Server- oder Proxy-Logs, dass der Key bei Wiederholungen übereinstimmt.
Fehler 2. Der Key ändert sich zusammen mit dem Body beim „Korrigieren“ der Anfrage
Der Client hat wegen eines ungültigen Felds einen 400 erhalten, das Feld korrigiert und mit demselben Key wiederholt. Der Server mit Fingerprint-Prüfung gibt 422 zurück. Ein Server ohne Prüfung gibt den gecachten Fehler 400 zurück, und der Client rennt gegen eine Wand. Eine korrigierte Anfrage ist ein neuer Vorgang und braucht einen neuen Key.
Fehler 3. Key-Prüfung über SELECT, dann INSERT
Oben bereits behandelt, aber wir wiederholen es: Zwischen Lesen und Schreiben schlüpft eine parallele Wiederholung durch. Besonders häufig zeigt sich das bei der Arbeit über Proxys, weil Client-Timeouts Wiederholungen im Abstand von Sekunden erzeugen und die Bestellverarbeitung genauso lange dauert. Nur atomare Reservierung hilft.
Fehler 4. Idempotenz über IP oder Session
Der Server „merkt sich“, dass es von dieser IP gerade dieselbe Anfrage gab, und lehnt die Wiederholung ab. Bei der Rotation eines mobilen Proxys kommt die Wiederholung von einer anderen Adresse, und der Schutz greift nicht. Die umgekehrte Variante ist auch schlecht: Legitime verschiedene Bestellungen von derselben Proxy-Adresse (Sie haben ja viele Clients hinter einer IP) werden als Duplikate abgelehnt. Der Key muss explizit sein und vom Client übergeben werden.
Fehler 5. Zu kurze TTL
Keys leben fünf Minuten, „um Redis nicht zu verstopfen“. Ein Netzwerkausfall dauert zwanzig Minuten. Die Retry-Warteschlange erreicht den Vorgang nach einer halben Stunde. Der Key ist vergessen, die Bestellung wird ein zweites Mal angelegt. Die TTL muss das längste realistische Szenario einer verzögerten Wiederholung abdecken.
Fehler 6. Cachen von Infrastrukturfehlern
Der erste Versuch scheiterte mit 500 wegen vorübergehender Datenbank-Nichtverfügbarkeit. Der Server hat die 500 als Ergebnis unter dem Key gespeichert. Alle weiteren Wiederholungen erhalten die 500 aus dem Cache, obwohl die Datenbank längst wieder läuft. Der Client muss den Key wechseln und verliert die Verbindung zum ursprünglichen Vorgang. Nur deterministische Ergebnisse dürfen gecacht werden.
Fehler 7. Zusammenfalten des Zustands unknown
Nach dem Ausschöpfen der Versuche markiert der Client den Vorgang als failed und lässt den Nutzer die Bestellung erneut aufgeben. Aber der Server hat den ersten Vorgang ausgeführt. Der Nutzer erhält zwei Bestellungen und eine doppelte Abbuchung. Der Zustand unknown muss explizit existieren und durch den Abgleich aufgelöst werden, nicht durch eine optimistische Annahme.
Fehler 8. Wiederholung nicht-idempotenter Vorgänge „weil es einfacher ist“
Eine universelle Retry-Schicht wiederholt alle Anfragen gleich, einschließlich POST ohne Keys. Das funktioniert bis zum ersten Netzwerksturm, nach dem innerhalb einer Stunde Hunderte Duplikate auftauchen. Die Retry-Schicht muss wissen, welche Anfragen wiederholt werden dürfen, und sich weigern, nicht-idempotente ohne expliziten Key zu wiederholen.
Fehler 9. Ein Key für einen Batch
Der Client sendet ein Array mit hundert Bestellungen und einem Key. Der Server hat sechzig verarbeitet und ist abgestürzt. Eine Wiederholung mit demselben Key erhält 409 oder einen teilweisen Snapshot. Wie soll man herausfinden, welche vierzig angelegt werden müssen? Für Batches braucht man entweder einen Key pro Position, eine serverseitige Garantie der Atomarität des gesamten Batches oder eine Antwort mit Status pro Element. Ohne das sind Batches über einen instabilen Kanal eine Quelle des Chaos.
Fehler 10. Fehlender Key in den Logs
Das Duplikat ist passiert, und Sie versuchen zu verstehen, ob es eine Wiederholung mit demselben Key war (Server-Bug) oder zwei verschiedene Vorgänge (Client-Bug). In den Logs fehlt der Key. Die Untersuchung wird zum Rätselraten. Der Key muss in jeder Logzeile auf beiden Seiten stehen und im Proxy-Journal, wenn der Proxy-Dienst Header-Logging unterstützt.
Werkzeuge und Ressourcen für die Implementierung
Auf der Client-Seite
- ID-Bibliotheken. Generatoren für UUIDv7 und ULID gibt es für alle gängigen Sprachen. Wählen Sie solche, die Monotonie innerhalb einer Millisekunde garantieren, wenn die Keys in Indizes der Server-Datenbank gelangen.
- HTTP-Clients mit getrennten Timeouts. Stellen Sie sicher, dass Ihr Client getrennt einen Timeout für die Verbindung zum Proxy und einen für das Lesen der Antwort setzen kann. Die meisten modernen Clients können das, aber standardmäßig ist oft ein einziger Timeout eingestellt.
- Warteschlangen mit Zustellgarantie. Für die Outbox-Implementierung eignet sich jedes Broker-System mit Verarbeitungsbestätigung. Wichtig ist, dass die Nachrichten-ID zwischen erneuten Zustellungen stabil bleibt – sie eignet sich gut als Grundlage für den Key.
- Proxy-Management-API. Gute mobile Proxy-Dienste haben eine Programmierschnittstelle, die den Kanalzustand, die Zeit bis zur Rotation und den IP-Wechsel auf Anfrage abfragt. Die Integration mit dieser API ermöglicht es, kritische Vorgänge nicht vor der Rotation zu starten und die Route zwischen Versuchen bewusst zu wechseln.
Auf der Server-Seite
- Relationale Datenbank mit Unique-Indizes. Die zuverlässigste Variante für den Key-Speicher, wenn die Volumina es zulassen. Ein Insert mit Konfliktbehandlung ist von Haus aus atomar.
- Redis oder ein Äquivalent. Für hochbelastete Systeme: SET mit den Flags NX und EX zur Reservierung, ein separater Key für den Antwort-Snapshot. Denken Sie an das Risiko von Datenverlust bei einem Knotenausfall und konfigurieren Sie Persistenz.
- Idempotenz-Middleware. Für populäre Web-Frameworks gibt es fertige Zwischenschichten, die den Basisvertrag implementieren: Reservierung, Fingerprint, Snapshot. Prüfen Sie, wie sie sich bei konkurrierenden Wiederholungen und bei einem Absturz zwischen Ausführung und Festschreibung verhalten – genau dort trennt sich gute von formeller Implementierung.
- API-Gateways. Manche Gateways können eine Deduplizierung anhand des Headers am Eingang durchführen. Das entlastet die Anwendung, aber das Gateway kennt normalerweise nicht das Geschäftsergebnis und kann Infrastrukturfehler cachen. Verwenden Sie es als ersten Filter, nicht als einzigen Schutz.
Tests
- Injektion von Netzwerkfehlern. Proxy-Testwerkzeuge, die die Verbindung nach dem Senden der Anfrage, aber vor der Antwort abbrechen, die Antwort länger als den Timeout verzögern, 502 und 504 zurückgeben können. Ohne solche Tests sehen Sie das Systemverhalten im einzig wichtigen Szenario nicht.
- Konkurrenztests. Gleichzeitiges Senden von N Anfragen mit einem Key. Erwartetes Ergebnis: genau eine angelegte Entität, N-1 Antworten 409 oder Snapshots. Jedes andere Ergebnis ist ein Defekt.
- Test auf Neustart mitten im Vorgang. Den Prozess nach dem Anlegen der Bestellung, aber vor der Festschreibung des Keys killen. Prüfen, ob der Mechanismus zur Wiederherstellung hängender Datensätze funktioniert hat.
- Rotationstest. Der erste Versuch über eine IP, die Wiederholung über eine andere. Prüfen, ob der Server den Snapshot zurückgegeben hat und die Wiederholung nicht durch eine Heuristik abgelehnt hat.
Standards und Dokumente
Der IETF-Spezifikationsentwurf zum Idempotency-Key-Header ist der Ausgangspunkt für die Formulierung des Vertrags: Dort sind Header-Name, Konfliktsemantik und empfohlene Antwortcodes definiert. Die öffentliche Dokumentation großer Zahlungsdienstleister ist ein gutes Vorbild dafür, wie man den Vertrag für externe Integratoren beschreibt: TTL, Verhalten bei Body-Nichtübereinstimmung, Behandlung konkurrierender Anfragen. Der Abschnitt über idempotente Methoden in der HTTP-Semantikspezifikation erklärt, warum PUT und DELETE wiederholt werden können, POST aber nicht, und das sollte man vor dem Entwurf von Endpunkten noch einmal lesen.
Fälle und Ergebnisse
Fall 1. Bestellaggregator und 47 Duplikate pro Monat
Ein Aggregatorunternehmen übergab Bestellungen an das System eines Logistikpartners über einen Pool mobiler Proxys mit Rotation alle fünf Minuten. Das Volumen lag bei etwa 12.000 Bestellungen pro Tag. Idempotenz-Keys gab es nicht: Die Partner-API dokumentierte sie nicht. Duplikate wurden einmal im Monat beim Finanzabgleich entdeckt, jedes kostete im Schnitt 900 Rubel für Stornierung, Rückerstattung und manuelle Arbeit.
Die Diagnose anhand der Proxy-Logs zeigte: 0,4% der Anfragen endeten mit einem Verbindungsabbruch nach dem Senden des Bodys und vor dem Erhalt der Antwort, überwiegend in den Minuten der Rotation. Der Retry lief nach drei Sekunden, und in 30% der Fälle war der erste Versuch zu diesem Zeitpunkt bereits ausgeführt. Die Rechnung stimmte mit den beobachteten Duplikaten überein.
Die Lösung in drei Schritten. Erstens stellte sich heraus, dass die API des Partners ein Feld external_id akzeptiert und Duplikate darüber ablehnt, obwohl dies in der Dokumentation nur in einer Zeile erwähnt wurde. Das Feld wurde mit einer stabilen Kennung aus der lokalen Outbox befüllt. Zweitens wurden die Rotationsfenster mit dem Versand synchronisiert: 15 Sekunden vor der Rotation wurden keine neuen Bestellungen mehr gesendet. Drittens wurde alle 10 Minuten ein Abgleich hinzugefügt. Das Ergebnis im Quartal: null Duplikate, die Zahl der Wiederholungen sank um 70% durch die Synchronisierung mit der Rotation, die durchschnittliche Bestellzeit stieg um 1,2 Sekunden durch das Warten auf die Fenster – ein akzeptabler Preis.
Fall 2. Zahlungsdienst und konkurrierende Wiederholungen
Ein Fintech-Dienst implementierte Idempotenz auf seiner Seite: Der Header wurde akzeptiert, der Key in der Datenbank gespeichert, bei einer Wiederholung der Snapshot zurückgegeben. Duplikate traten trotzdem auf, selten, aber regelmäßig: etwa eines pro 40.000 Vorgänge. Die Untersuchung zeigte, dass die Key-Prüfung über ein Lesen und dann über ein Schreiben erfolgte, und Clients mit aggressiven Timeouts (zwei Wiederholungen innerhalb einer Sekunde über verschiedene Proxys) trafen genau in das Fenster dazwischen.
Man ersetzte es durch ein Insert mit Unique-Index und fügte den Zustand in_progress mit der Antwort 409 und dem Header Retry-After von einer Sekunde hinzu. Eine Metrik für konkurrierende Wiederholungen wurde ergänzt. Sie zeigte etwas Unerwartetes: 2% aller Vorgänge erhalten mindestens ein 409, das heißt, die Clients wiederholen viel aggressiver als angenommen. Der Dienst aktualisierte die Dokumentation mit Empfehlungen zu Timeouts, und nach zwei Monaten sank der Anteil der 409 auf 0,3%. Duplikate: null in einem halben Jahr.
Fall 3. Marktplatz-Integration und Batches
Ein Verkäufer lud Bestände und Preise in Batches von 500 Positionen über einen Proxy auf den Marktplatz. Die Idempotenz des Batches galt für die gesamte Anfrage. Bei einem Verbindungsabbruch wurde die Wiederholung entweder abgelehnt (Batch in Bearbeitung) oder lieferte einen Snapshot des teilweisen Ergebnisses, aus dem nicht hervorging, welche Positionen aktualisiert wurden. Der Verkäufer schloss daraus „nicht aktualisiert“ und lud erneut hoch, was Rennen zwischen dem alten und dem neuen Batch erzeugte.
Die Lösung: Umstellung auf Batches mit positionsweisen Vorgangskennungen und Abfrage des Status pro Position nach einem ungewissen Abschluss. Die Batch-Größe wurde auf 100 Positionen reduziert, damit die Verarbeitungszeit den Timeout nicht überschreitet. Die Zahl der „hängenden“ Aktualisierungen sank von Dutzenden pro Tag auf null, und die Bestandsabweichungen, die zuvor regelmäßig zu Stornierungen von Kundenbestellungen geführt hatten, verschwanden.
Fall 4. Automatisierter Agent und Ketten-Wiederholungen
Trend des Jahres 2026: Immer mehr Integrationen werden von autonomen Agenten auf Basis großer Sprachmodelle ausgeführt, die APIs nach Anweisungen aufrufen. Ein Team führte einen solchen Agenten für die Beschaffung bei Lieferanten ein. Bei einer ungewissen Antwort „überlegte“ der Agent und beschloss, den Vorgang zu wiederholen, wobei er eine neue Anfrage erzeugte. Keys gab es nicht, da der Agent den Aufruf jedes Mal neu bildete. In der ersten Woche entstanden 11 doppelte Beschaffungen.
Die Korrektur: Dem Agenten wurde verboten, Erstellungsanfragen direkt zu bilden. Er legt einen Absichtsdatensatz in der Outbox über ein internes Werkzeug an, und der Versand wird von einem deterministischen Dienst mit Keys und Abgleich ausgeführt. Der Agent erhält nur den Endstatus. Die Duplikate verschwanden, und gleichzeitig entstand eine vollständige Nachverfolgung, wer und warum jede Beschaffung initiiert hat. Die allgemeine Schlussfolgerung: Autonome Systeme mit der Fähigkeit zu Wiederholungen sind eine neue und mächtige Quelle von Duplikaten, und die Idempotenz-Barriere ist für sie zwingend.
FAQ: schwierige Fragen zu Idempotenz und Wiederholungen
Braucht man einen Idempotenz-Key für PUT und DELETE, wenn sie per Spezifikation idempotent sind?
Formal nicht: Eine Wiederholung von PUT mit demselben Body liefert denselben Zustand. Aber es gibt Feinheiten. Wenn PUT bei der Erstellung 201 und bei der Aktualisierung 200 zurückgibt, liefert die Wiederholung einen anderen Status, und der Client kann ihn anders interpretieren. DELETE gibt bei einer Wiederholung 404 statt 204 zurück, was oft als Fehler behandelt wird. Ein Key mit einem Antwort-Snapshot macht das Verhalten vorhersehbar. Wenn PUT außerdem Nebenwirkungen auslöst (Benachrichtigung senden, Audit schreiben), werden sie erneut ausgeführt. Die Idempotenz der Methode ist nicht gleich der Idempotenz aller Nebenwirkungen.
Was tun, wenn der Server 409 in_progress zurückgibt, der erste Versuch aber tatsächlich gestorben ist?
Das ist die Verantwortung des Servers: Er muss einen Mechanismus zur Wiederherstellung hängender Datensätze mit einer Zeitschwelle haben. Der Client sollte nicht unendlich auf 409 warten, sondern eine begrenzte Anzahl von Malen (zum Beispiel bis zu zwei Minuten), danach den Vorgang auf unknown setzen und in den Abgleich übergeben. Wenn der Server systematisch in_progress länger als vernünftig hält, ist das ein Implementierungsdefekt, den man dem API-Eigentümer melden sollte.
Wie steht es um den Key, wenn die Anfrage über mehrere Proxys in einer Kette läuft?
Nichts Besonderes: Der Key wird im Header übergeben und läuft transparent durch jede Kette. Das Einzige, was man prüfen sollte: Ob ein Zwischenknoten ungewöhnliche Header entfernt. Manche Unternehmens-Gateways filtern Header nach einer Whitelist. Ein einfacher Test: Eine Anfrage durch die ganze Kette an einen eigenen Debug-Endpunkt senden und prüfen, ob der Header angekommen ist.
Kann man den Hash des Request-Bodys als Key verwenden und beim Client nichts speichern?
Man kann, aber mit Einschränkungen. Zwei verschiedene Bestellungen mit gleichem Inhalt (derselbe Artikel, derselbe Betrag, derselbe Käufer) erhalten denselben Key, und die zweite wird als Wiederholung abgelehnt. Um das zu vermeiden, fügt man dem Body eine eindeutige Komponente hinzu – eine Warenkorb-ID oder eine lokale laufende Nummer. Dann wird der Hash des Bodys zu einem deterministischen Key des Vorgangs. Dieser Ansatz ist praktisch für Clients ohne zuverlässigen lokalen Speicher, erfordert aber eine strikte Normalisierung des Bodys: Eine Änderung der Feldreihenfolge in JSON ändert den Hash.
Wie lange soll man vor einer Wiederholung warten, damit der Server den ersten Versuch abschließen kann?
Das ist eine Frage der Retry-Policy, aber aus Sicht des Vertrags ist eines wichtig: Wenn der Server in_progress mit 409 unterstützt, muss man nicht „nach Gefühl“ warten – der Server sagt selbst, dass der Vorgang noch läuft. Wenn der Server diesen Zustand nicht hat, muss das Intervall vor der Wiederholung das 99. Perzentil der Verarbeitungszeit auf dem Server überschreiten. Man kann es aus der Dokumentation, aus den Metriken erfolgreicher Anfragen oder empirisch in einer Testumgebung ermitteln.
Sollte man Lesevorgänge idempotent machen?
GET ist per Definition idempotent, ein Key ist nicht nötig. Aber es gibt eine Ausnahme: „Lesen mit Nebenwirkung“, zum Beispiel ein GET, das eine Benachrichtigung als gelesen markiert oder ein Limit abbucht. Das ist ein architektonischer Geruch; solche Vorgänge sollten besser in POST mit Key umgewandelt werden, als Idempotenz an GET zu schrauben.
Was macht man mit Keys bei einer Migration oder einem API-Versionswechsel?
Nehmen Sie die Endpunktversion in den Geltungsbereich des Keys auf dem Server auf. Dann kollidiert ein in v1 verwendeter Key nicht mit demselben Key in v2. Für den Client ist die Regel einfach: Eine Migration bedeutet neue Vorgänge mit neuen Keys, alte Keys werden nicht übertragen. Wenn ein Vorgang zum Zeitpunkt der Migration im Zustand unknown war, lösen Sie ihn zuerst per Abgleich auf und migrieren Sie dann.
Wie erklärt man dem Business, warum man einen Sprint in Idempotenz investieren soll, wenn Duplikate „fast nie vorkommen“?
Berechnen Sie die Kosten eines Duplikats: Stornierung, Rückerstattung, Support, Reputation, manchmal Vertragsstrafen des Partners. Multiplizieren Sie das mit der beobachteten Häufigkeit. Zeigen Sie dann, dass die Häufigkeit bei Netzwerkvorfällen nichtlinear wächst: an einem ruhigen Tag null Duplikate, an einem Tag mit einem Ausfall eines Netzbetreibers Hunderte in einer Stunde. Idempotenz ist eine Versicherung mit bekannter Prämie und unbekanntem, aber potenziell enormem Gewinn. Außerdem hat sie einen Nebeneffekt: die Möglichkeit, Anfragen aggressiv zu wiederholen, ohne Angst, was die Erholung nach Störungen beschleunigt.
Erhöht Idempotenz die Last auf dem Server?
Unwesentlich: ein zusätzliches Schreiben und ein Lesen pro Vorgang. Dafür senkt sie die Last in Notfallszenarien, weil eine Wiederholung den Snapshot in Millisekunden zurückgibt statt der vollständigen Verarbeitung der Bestellung. Bei einem Wiederholungssturm hält ein Server mit Idempotenz der Last besser stand als ohne – das ist kontraintuitiv, wird aber durch die Praxis bestätigt.
Fazit: Vertrag statt Hoffnung
Fassen wir das Wichtigste zusammen. Jedes Netzwerk stellt Anfragen nach dem Prinzip „mindestens einmal“ zu. Proxys – besonders mobile, mit Rotation und Funkkanal – machen Wiederholungen nicht zur Seltenheit, sondern zur Norm. Die Retry-Policy beantwortet die Frage „wann und wie wiederholen“. Idempotenz beantwortet die Frage „warum eine Wiederholung nichts kaputt macht“. Ohne die zweite Antwort ist die erste gefährlich.
Eine sichere Wiederholung ruht auf drei Säulen. Der Key des Vorgangs, geboren vor dem ersten Versuch und lebend in Ihrer Datenbank, nicht im HTTP-Client. Der serverseitige Vertrag mit atomarer Reservierung, Zustand in_progress, Body-Fingerprint, Antwort-Snapshot und vernünftiger TTL. Der Abgleich als letzte Verteidigungslinie für Vorgänge, die in der Ungewissheit feststecken. Wenn der Server keinen Vertrag bietet, übernimmt die Rolle des Keys eine natürliche Kennung und die Rolle des Speichers Ihre Outbox.
Was Sie als Nächstes tun sollten, noch heute:
- Finden Sie in Ihren Integrationen alle POST-Vorgänge, die automatisch wiederholt werden. Beantworten Sie für jeden: Gibt es einen Key, wo wird er erzeugt, stimmt er bei Wiederholungen überein?
- Lesen Sie die Dokumentation der Partner-APIs auf Felder external_id und den Header Idempotency-Key. Prüfen Sie das Verhalten in einer Testumgebung mit zwei identischen Anfragen.
- Fügen Sie den Zustand unknown in Ihr Vorgangsmodell und einen Abgleichprozess dafür hinzu.
- Wenn Sie den Server besitzen, führen Sie drei Tests durch: konkurrierende Wiederholungen, Absturz zwischen Ausführung und Festschreibung, Wiederholung von einer anderen IP.
- Bringen Sie das Verhältnis von Wiederholungen zu eindeutigen Vorgängen auf ein Dashboard. Das ist Ihr Indikator für die Gesundheit des Kanals durch den Proxy.
Idempotenz ist ein seltener Fall, in dem sich Ingenieursdisziplin direkt in geschäftliche Ruhe umrechnet. Ein einmal entworfenes Vertragswerk schützt jahrelang vor Duplikaten, Wiederholungsstürmen und nächtlichen Anrufen aus der Buchhaltung. Und ehrlich gesagt liegt eine besondere Freude darin, auf ein Diagramm mit Tausenden Wiederholungen über einen instabilen Kanal zu schauen und in der Spalte der Duplikate eine sichere Null zu sehen.