Idempotency Keys in APIs – doppelte Requests sicher verhindern

Ein Klassiker im Alltag: Ein Nutzer klickt zweimal auf „Kaufen“, die App hängt kurz, ein Load-Balancer wiederholt Requests, oder ein Client führt automatisch Retries aus. Ohne Schutz kann daraus schnell eine doppelte Bestellung werden. Genau hier helfen Idempotency Keys: Sie sorgen dafür, dass ein API-Aufruf mit denselben Eingaben nur einmal „zählt“, auch wenn er technisch mehrfach gesendet wird.

Warum doppelte Requests überhaupt entstehen

Viele Duplikate sind keine „Fehler“, sondern normale Effekte verteilter Systeme. Besonders häufig passiert das bei Vorgängen, die Geld, Kontingente oder Buchungen betreffen.

Typische Auslöser im Web und Mobile

• Retries des Clients nach Timeout (z. B. Mobilfunkwechsel oder kurze Netzunterbrechung)
• Browser sendet ein Formular erneut (Reload, Back/Forward, Auto-Fill-Workflows)
• Der Nutzer klickt mehrfach, weil keine schnelle Rückmeldung kommt
• Reverse Proxy / Gateway bricht Verbindungen ab, obwohl der Backend-Request weiterläuft
• Queues oder Worker starten Jobs erneut nach Abstürzen

Wichtig: Selbst wenn ein Request im Client „fehlgeschlagen“ wirkt, kann er im Server erfolgreich gewesen sein. Genau diese Unsicherheit führt zu doppelten Ausführungen.

Idempotent vs. „einmalig“: ein kurzer Begriffsklärer

„Idempotent“ bedeutet: Derselbe Aufruf kann mehrfach passieren, das Ergebnis bleibt gleich. Bei HTTP ist das für GET (lesen) grundsätzlich gegeben. Bei POST (anlegen/ausführen) ist es das meist nicht, weil jeder POST eine neue Aktion auslösen kann. Idempotency ist deshalb ein Zusatzkonzept, das sichere Wiederholungen für kritische POST/PUT-ähnliche Aktionen ermöglicht.

Wie Idempotency Keys funktionieren (Prinzip)

Die Idee ist einfach: Der Client sendet zu einem Request eine eindeutige Kennung mit. Der Server merkt sich, dass diese Kennung bereits verarbeitet wurde, und liefert bei Wiederholung nicht „nochmal ausführen“, sondern „gleiches Ergebnis wie beim ersten Mal“.

Das Grundmuster in 3 Schritten

• Client erzeugt einen zufälligen, eindeutigen Key (z. B. UUID) pro Aktion.
• Client sendet den Key in einem Header, z. B. Idempotency-Key.
• Server speichert Key + Ergebnis (oder Referenz) und gibt bei Duplikaten die gespeicherte Antwort zurück.

Damit wird aus einem „unsicheren POST“ praktisch ein sicher wiederholbarer Vorgang, ohne dass der Client komplexe Logik bauen muss.

HTTP-Design: Header, Statuscodes und Antworten

In der Praxis ist ein klarer Vertrag entscheidend: Welche Requests dürfen einen Key nutzen? Wie lange ist er gültig? Was passiert, wenn Payload oder Nutzerkontext nicht passen?

Empfohlene Request-Form

Ein gängiges Muster sieht so aus:

• POST /orders
• Header: Idempotency-Key: <random>
• Body: die Bestelldaten

Der Key gehört pro „Business-Aktion“ genau einmal verwendet, nicht pro Retry. Retries sollen denselben Key wiederverwenden.

Welche Response sollte bei Duplikaten zurückkommen?

Viele APIs geben bei Wiederholung exakt denselben Body und Statuscode zurück wie beim ersten Durchlauf (z. B. 201 Created mit Order-ID). Das ist für Clients am einfachsten zu handhaben.

Wichtig ist Konsistenz: Wenn ein Key bereits verarbeitet wurde, sollte der Server keinen neuen Datensatz erzeugen und auch keine neue Nebenwirkung auslösen.

Wenn zu demselben Key eine andere Payload geschickt wird, ist das ein echter Konflikt. Dann ist eine klare Fehlermeldung sinnvoll (oft 409 Conflict), damit der Client den Fehler sieht statt stillschweigend „falsche“ Ergebnisse zu bekommen. Wenn Statuscodes im Team öfter diskutiert werden, hilft der Überblick aus HTTP Statuscodes verstehen – Fehler sauber behandeln.

Backend-Implementierung: so bleibt es wirklich sicher

Der schwerste Teil ist nicht der Header, sondern die korrekte Speicherung und Absicherung im Backend. Es reicht nicht, nur „Key gesehen“ zu speichern – es muss auch bei parallelen Requests funktionieren.

Speicherstrategie: was wird pro Key abgelegt?

Mindestens nötig:

• Idempotency-Key
• Scope (z. B. User-ID oder API-Key), damit Keys nicht zwischen Nutzern kollidieren
• Hash der Request-Payload (oder relevante Felder), um „gleicher Key, andere Daten“ zu erkennen
• Status (in Bearbeitung / abgeschlossen / fehlgeschlagen)
• Response-Daten oder eine Referenz (z. B. erzeugte Order-ID)
• Ablaufdatum (TTL), damit die Tabelle nicht ewig wächst

Parallelität: Race Conditions verhindern

Wenn zwei identische Requests gleichzeitig eintreffen, müssen sie sich gegenseitig „sehen“. Sonst erzeugen beide eine Bestellung, bevor einer den Key speichert. Das lässt sich stabil lösen, indem die Speicherung atomar (unteilbar) passiert, typischerweise über einen Unique-Index in der Datenbank.

Praktisches Muster:

• Versuch, einen Datensatz (scope + key) anzulegen.
• Wenn erfolgreich: der Request „besitzt“ den Key und verarbeitet die Aktion.
• Wenn Unique-Verletzung: Key existiert schon → gespeichertes Ergebnis zurückgeben (oder warten, wenn noch „in Bearbeitung“).

Bei längeren Vorgängen kann ein „in Bearbeitung“-Status wichtig sein, damit ein zweiter Request nicht sofort scheitert, sondern das Ergebnis später abrufen kann (je nach API-Design).

Datenbank, Cache oder beides?

Für kritische Aktionen ist die Datenbank oft die robusteste Wahl, weil sie Konsistenz und Unique-Constraints zuverlässig abbildet. Ein Cache (z. B. Redis) kann ergänzen, um fertige Antworten schnell auszuliefern, sollte aber nicht der einzige Ort sein, wenn Datenverlust inakzeptabel ist.

Ein kleines Fallbeispiel: Checkout mit unsicherem Netz

Eine Mobile-App sendet POST /payments. Nach 8 Sekunden Timeout zeigt die App „Zahlung fehlgeschlagen“ und der Nutzer tippt erneut. Ohne Idempotency Key entstehen zwei Zahlungen. Mit Key passiert Folgendes:

• Erster Request startet, Server legt Key an und verarbeitet die Zahlung.
• App sendet erneut denselben Key (Retry oder erneuter Tap).
• Server erkennt den Key und liefert die erste Payment-ID zurück, statt erneut abzubuchen.

Das senkt nicht nur das Risiko von Doppelbuchungen, sondern reduziert auch Support-Aufwand und „unerkärliche“ Zustände im System.

Praxis-Box: robuste Umsetzung in kurzen Schritten

• Definiere, welche Endpoints einen Idempotency-Key akzeptieren (meist POST für Create/Execute).
• Lege den Scope fest (mindestens pro Nutzer oder pro API-Client).
• Speichere Key + Payload-Hash + Ergebnisreferenz in einer Tabelle mit Unique-Constraint.
• Behandle parallele Requests sauber: Insert zuerst, dann ausführen; bei Konflikt Ergebnis zurückgeben.
• Setze ein Ablaufdatum (TTL) und räume alte Keys regelmäßig auf.
• Dokumentiere klar, wie sich der Server bei „gleicher Key, andere Payload“ verhält (Konflikt statt still).

Häufige Stolperfallen und wie sie vermeidbar sind

Key nur auf Client-Seite „merken“

Wenn der Client den Key erzeugt, aber der Server ihn nicht dauerhaft prüft und speichert, ist nichts gewonnen. Der Schutz muss serverseitig passieren, sonst bleiben Race Conditions und doppelte Nebenwirkungen möglich.

Keys nicht scopen (Kollisionen zwischen Nutzern)

Ein Key sollte nie global „für alle“ gelten. Sonst kann ein zufällig gleicher Wert (oder ein absichtlich wiederverwendeter) den falschen Response liefern. Der sichere Ansatz: Key immer zusammen mit einem Kontext speichern, z. B. User-ID oder API-Key.

Nur „bereits gesehen“ speichern, aber keine Antwort

Wenn nur gespeichert wird, dass ein Request existiert, fehlen dem wiederholenden Client wichtige Informationen (z. B. die erzeugte ID). Das führt zu Folgeproblemen: Der Client fragt dann andere Endpoints ab oder erstellt am Ende doch erneut. Besser: Response oder mindestens die erzeugte Ressourcen-ID ablegen.

Payload-Wechsel bei gleichem Key nicht erkennen

Wenn derselbe Key mit anderen Daten wiederkommt, ist das kein Retry, sondern inkonsistentes Verhalten im Client oder ein Bug. Ein gespeicherter Hash der relevanten Felder macht den Konflikt sichtbar und schützt davor, versehentlich „falsche“ Ergebnisse zurückzugeben.

Idempotency Keys und angrenzende Konzepte

Idempotency Keys lösen „doppelt ausführen“ bei unsicheren POST-Requests. Sie ersetzen aber nicht andere Sicherheits- und Robustheitsmechanismen:

• Für wiederholbare Requests im Allgemeinen sind saubere Fehlerantworten entscheidend. Dazu passt API-Fehler richtig behandeln – robuste Webanwendungen Schritt für Schritt.
• Wenn Clients automatisch retryn, hilft ein bewusster Umgang mit Timeouts und Wiederholungen. Das ergänzt Idempotency, ersetzt sie aber nicht.
• Für eventbasierte Systeme (Webhooks) ist das Thema eng verwandt: auch dort muss „doppelt geliefert“ abgefangen werden. Dazu passt Webhooks robust bauen – Signaturen, Retries, Idempotency.

Entscheidungshilfe: wann sich der Aufwand lohnt

• Wenn ein Request Geld abbucht, Reservierungen auslöst oder Kontingente reduziert
  • Idempotency Key fest einplanen und dokumentieren
• Wenn ein Request „nur“ Daten speichert, aber Duplikate später aufräumbar sind
  • Idempotency Keys sind sinnvoll, aber optional – abhängig vom Produkt und Support-Aufwand
• Wenn ein Endpoint ohnehin idempotent ist (z. B. PUT mit stabiler Resource-ID)
  • Oft reicht das HTTP-Design, ein zusätzlicher Key ist nicht zwingend

Richtig umgesetzt werden Race Conditions bei kritischen Aktionen deutlich seltener sichtbar, weil Wiederholungen nicht mehr zu neuen Nebenwirkungen führen. Das macht APIs stabiler, ohne Clients mit komplizierten Workarounds zu belasten.