Timeout ist kein sicherer Fehlschlag
Stellen Sie sich einen Exportauftrag vor. Der Server nimmt ihn an, speichert ihn und beginnt die Arbeit. Bevor die Antwort den Client erreicht, bricht die Verbindung ab. Der Client sieht einen Netzwerkfehler, während der Export bereits existiert. Umgekehrt kann die Anfrage den Server gar nicht erreicht haben. Aus demselben lokalen Fehlersignal folgen also verschiedene Zustände.
Speichern Sie deshalb für wichtige Aktionen eine vom Client oder Server vereinbarte Auftragskennung. Sie ermöglicht, den Status später wiederzufinden. Zeigen Sie einen unklaren Ausgang als „wird geklärt“ an, wenn diese Aussage zutrifft; setzen Sie ihn nicht allein nach Zeitablauf auf „fehlgeschlagen“. Ein dauerhaft offener Zustand braucht einen verantwortlichen Klärungsweg.
Das Problem betrifft auch Fehlerantworten. Stripe beschreibt 500-Antworten bei bestimmten schreibenden Vorgängen ausdrücklich als möglicherweise unklaren Ausgang. Ein neuer Idempotenzschlüssel kann dann einen zweiten Vorgang auslösen. Das ist ein konkretes Beispiel für einen API-Vertrag, keine allgemeine Aussage, dass jede 500-Antwort bereits eine Wirkung hatte. Stripe: Advanced error handling.
Was HTTP mit idempotent meint
Eine Operation ist idempotent, wenn mehrere identische Aufrufe dieselbe beabsichtigte Wirkung haben wie einer. Identische Antwortbytes sind dafür nicht nötig. Ein wiederholtes DELETE kann etwa zuerst die erfolgreiche Entfernung und später ein nicht mehr vorhandenes Objekt melden. Auch zusätzliche Logeinträge widersprechen der HTTP-Definition nicht.
HTTP definiert unter anderem PUT, DELETE und die sicheren Methoden als idempotent. Das setzt voraus, dass die Anwendung die Methodensemantik einhält. Ein GET, das versteckt einen kaufbaren Auftrag auslöst, wird nicht durch seinen Namen harmlos. Für nicht idempotente Anfragen darf ein Client automatische Wiederholung nicht allein aus einem Verbindungsabbruch ableiten; er braucht zusätzliche Kenntnis der Operation oder Gewissheit, dass sie nicht angewendet wurde. RFC 9110, Abschnitt 9.2.2.
Idempotenz ist außerdem keine Berechtigung. Jede Anfrage muss im aktuellen Sicherheitskontext zulässig sein. Eine gespeicherte Antwort darf nicht an jemanden gelangen, der zufällig denselben Schlüssel verwendet.
Ein Idempotenzschlüssel braucht einen Serververtrag
Ein Idempotenzschlüssel bezeichnet denselben logischen Auftrag über mehrere Zustellversuche hinweg. Der Client erstellt ihn vor dem ersten Versuch und bewahrt ihn zusammen mit dessen unveränderten Parametern auf. Der Server muss die Wiedererkennung tatsächlich implementieren. Ein beliebiger zusätzlicher Header allein verändert die Wirkung einer API nicht.
Vereinbaren Sie mindestens diese Punkte:
Bei schmaler Ansicht können Sie die Tabelle seitlich scrollen.
| Vertragsfrage | Sinnvolle Festlegung |
|---|---|
| Wo ist der Schlüssel eindeutig? | Beispielsweise innerhalb von Mandant, Operation und Schlüssel; die Identität stammt aus geprüfter Anmeldung. |
| Was gilt als derselbe Auftrag? | Ein stabil definierter Vergleich der relevanten Parameter; geänderte Inhalte werden abgelehnt. |
| Was passiert bei zwei gleichzeitigen Versuchen? | Eine atomare Annahme lässt höchstens einen Ausführungsweg beginnen. Der zweite erhält einen dokumentierten Zwischenstand. |
| Was wird gespeichert? | Bearbeitungszustand und ein zugriffsgeschützter Ergebnisverweis oder die vereinbarte Antwort. |
| Wie lange gilt die Wiedererkennung? | Ein veröffentlichtes Zeitfenster, das zum maximalen Wiederholungs- und Klärungszeitraum passt. |
| Wie wird ein unklarer Zustand geklärt? | Statusabfrage, Abgleich mit dem ausführenden Dienst oder geregelte manuelle Bearbeitung. |
Das folgende Ablaufbild ist ein Entwurf für einen Vertrag, kein direkt einsetzbarer Servercode:
Schematische Erklärung · keine Messung
Mehrere Versuche, derselbe fachliche Auftrag
- Client: Schlüssel vor dem ersten Versuch speichern
Schlüssel und unveränderte Parameter gehören zum selben logischen Auftrag.
- Server: Identität, Erlaubnis und Eingabe prüfen
Relevante Parameter festhalten. Danach
(Mandant, Operation, Schlüssel)atomar reservieren beziehungsweise den vorhandenen Eintrag erkennen.
Die atomare Entscheidung verzweigt nach dem gespeicherten Zustand
- Neuer Eintrag
- Definierten Ausführungsweg beginnen; den endgültigen Zustand dauerhaft festhalten.
- Gleicher Schlüssel, andere Parameter
- Ablehnen: Der Schlüssel darf keinen anderen Auftrag bezeichnen.
- Gleiche Parameter, noch offen
- Dokumentierten Zwischenstand liefern; keinen weiteren Ausführungsweg beginnen.
- Gleiche Parameter, abgeschlossen
- Das für diesen Aufrufer erlaubte Ergebnis wiedergeben.
Rückweg nach einer fehlenden Antwort
Ein Timeout beweist keinen Fehlschlag. Der Auftrag kann bereits wirken.
Status abfragen oder nach Vertrag mit gleichem Schlüssel und gleichen Parametern wiederholen.
Bedingung: Die Wiedererkennung gilt im vereinbarten Zeitfenster; jede Anfrage braucht die aktuelle Erlaubnis. Nach Ablauf zuerst den Ausgang klären. Ein neuer Schlüssel könnte einen zweiten Auftrag auslösen.
Ein lokaler Datenbank-Lock macht einen Fremdeffekt nicht atomar. Der Partner braucht einen passenden Idempotenzvertrag oder einen nachvollziehbaren Abgleich; die Skizze garantiert kein „Exactly once“.
Ein gewöhnliches „erst nachsehen, dann einfügen“ reicht bei Gleichzeitigkeit nicht. Die Eindeutigkeit und Zustandsänderung müssen vom verwendeten Speicher zuverlässig durchgesetzt werden. Bei einem externen Effekt entsteht zusätzlich eine Lücke zwischen lokaler Speicherung und Fremdsystem. Ein lokaler Datenbank-Lock macht den Versand beim Partner nicht atomar. Nutzen Sie dessen unterstützten Idempotenzvertrag oder einen nachvollziehbaren Abgleich; für komplexe Abläufe sind dauerhafte Auftrags- und Ereignisverfahren gesondert zu entwerfen.
Der IETF-Text zum Idempotency-Key-Header war am 27. September 2026 als Entwurf -07 abgelaufen und archiviert. Er liefert nützliche Vertragsfragen, ist aber kein verabschiedeter RFC. Seine Vorschläge zu Headerformat und Fehlercodes sind keine universelle Pflicht für vorhandene APIs. IETF: Entwurf und Status.
Stripe ist ein Beispiel für eine bestehende konkrete Umsetzung: Dort können wiederholte Anfragen innerhalb des Vertrags auch dieselbe gespeicherte 500-Antwort erhalten; Schlüssel dürfen nach dem dokumentierten Aufbewahrungsfenster entfernt werden. Übertragen Sie weder dessen Frist noch dessen Fehlerverhalten unbesehen auf andere Anbieter. Stripe: Idempotent requests.
Wann wiederholen, wann klären?
Bei schmaler Ansicht können Sie die Tabelle seitlich scrollen.
| Situation | Nächster Schritt |
|---|---|
| Die Eingabe ist ungültig oder der Zugriff verweigert. | Ursache beheben; denselben unveränderten Fehler nicht blind wiederholen. |
| 429 mit Retry-After und ein Vertrag erlaubt Wiederholung. | Wartehinweis beachten, Gesamtbudget prüfen und bei derselben Aktion den vereinbarten Schlüssel beibehalten. |
| Verbindungsfehler nach einem Schreibaufruf | Ausgang als unklar behandeln; Status oder Idempotenzvertrag nutzen. |
| Ein Auftrag ist noch in Bearbeitung. | Dokumentierten Statusweg verwenden; nicht durch neue Schlüssel weitere Aufträge erzeugen. |
| Der erlaubte Wiederholungszeitraum ist abgelaufen. | Ergebnis klären, bevor ein möglicherweise neuer Auftrag beginnt. |
Retry-After kann Sekunden oder ein HTTP-Datum enthalten. Es ist keine Zusage über späteren Erfolg und macht eine nicht idempotente Operation nicht automatisch sicher. Die Bedeutung eines 429-Status und die Betreiberseite erläutert Rate-Limits richtig planen. RFC 9110, Abschnitt 10.2.3.
Ein gemeinsames Zeit- und Wiederholungsbudget festlegen
Legen Sie eine Gesamtdauer fest, innerhalb derer der Auftrag sinnvoll abgeschlossen werden kann. Dazu gehören Verbindungsaufbau, Antwortzeit, Wartepausen und alle Versuche. Eine Bibliothek, ein Gateway und Ihr Anwendungscode sollten nicht unabhängig voneinander jeweils mehrfach wiederholen: Ihre Versuche können sich vervielfachen und eine Störung verschärfen.
Bei vorübergehenden Fehlern helfen wachsende Warteabstände. Eine kleine zufällige Streuung, häufig Jitter genannt, verhindert, dass viele Clients im gleichen Takt neu starten. Respektieren Sie dabei den serverseitigen Wartehinweis. Passt er nicht mehr in Ihr Gesamtbudget, brechen Sie den automatischen Versuch ab oder verschieben den Auftrag nach dem dafür vereinbarten Verfahren. „Abgebrochen“ auf Clientseite sagt weiterhin nichts darüber, ob eine frühere Ausführung schon wirkte.
Die konkrete Retry-Politik muss zum Dienst passen: Ein interaktiver Seitenaufruf und ein dauerhaft gespeicherter Hintergrundauftrag haben verschiedene Zeitziele. Microsoft beschreibt diese Abwägung und warnt vor aggressiven sowie ineinander geschachtelten Wiederholungen. Microsoft: Retry pattern.
Den Vertrag ohne echte Nebenwirkungen prüfen
Verwenden Sie einen isolierten Dienst mit synthetischen Aufträgen und einen simulierten Partner. Lassen Sie die Testantwort gezielt nach dauerhaftem Annehmen verloren gehen. Ein wiederholter Versuch muss denselben fachlichen Auftrag finden; die Anzahl ausgelöster Wirkungen darf nicht steigen. Prüfen Sie außerdem veränderte Parameter mit gleichem Schlüssel, gleichzeitige Zustellung, getrennte Mandanten und das Ende der Speicherfrist.
Für den unklaren Ausgang ist der Nachweis besonders wichtig: Unterbrechen Sie im Test den Ablauf zwischen Fremdeffekt und lokaler Ergebnisablage. Der Auftrag darf danach weder still verschwinden noch ungeprüft als neue Aktion starten. Ein erfolgreicher Normalfall belegt diese Eigenschaft nicht.
Ändern Sie Schlüsselaufbau oder Aufbewahrungszeit nur mit Blick auf bereits offene Aufträge. Bei einer Rücknahme müssen deren Einträge lesbar und ihre Wiedererkennung wirksam bleiben. Löschen Sie den Idempotenzspeicher nicht als vermeintlich einfache Fehlerbehebung. Bei Konflikten kann es sicherer sein, neue Schreibaufträge kurz auszusetzen und vorhandene zu klären.
Die Abläufe dieses Artikels wurden nicht an einer produktiven API erprobt. Der öffentliche API Security Check prüft weder doppelte Wirkungen noch Idempotenzspeicher oder Client-Retries. Die passenden Nachweise entstehen in Ihrer Anwendung und ihren Integrationstests. Für mehrere unterschiedliche, jeweils gültige Aufträge führt Geschäftslogik absichern weiter; für später zugestellte Ergebnisse der Webhook-Ratgeber.
Quellen und Stand
Quellenstand: 27. September 2026. Die Links stehen zusätzlich bei den jeweils begründeten Aussagen.