Idempotenz (Idempotency Key)

Ein Idempotency-Key sorgt dafür, dass wiederholte API-Anfragen nur einmal wirken, etwa bei Zahlungen. Funktionsweise und Praxis.

Idempotenz bedeutet, dass eine Operation bei mehrfacher Ausführung dasselbe Ergebnis hat wie bei einmaliger. Bei APIs wird das oft über einen Idempotency-Key erreicht.

Das Problem

Netzwerke sind unzuverlässig. Sendet ein System eine Anfrage und erhält keine Antwort, weiß es nicht, ob die Anfrage verarbeitet wurde. Wiederholt es sie, kann eine Zahlung doppelt ausgelöst oder eine Rechnung doppelt erzeugt werden. Genau das soll Idempotenz verhindern.

Wie ein Idempotency-Key funktioniert

  1. Der Client erzeugt für jede fachliche Operation einen eindeutigen Schlüssel, meist eine zufällige ID, und sendet ihn mit der Anfrage, häufig als HTTP-Header.
  2. Der Server speichert Schlüssel und Ergebnis der ersten Verarbeitung.
  3. Kommt dieselbe Anfrage mit demselben Schlüssel erneut an, führt der Server sie nicht noch einmal aus, sondern liefert das gespeicherte Ergebnis zurück.

Der Schlüssel gehört zur Operation, nicht zum einzelnen Versuch. Ein Wiederholungsversuch verwendet also denselben Schlüssel, eine neue Operation einen neuen.

Wo es im Billing wichtig ist

  • Auslösen von Zahlungen und Lastschriften, auch beim Wiederholen fehlgeschlagener Zahlungen, siehe Payment Retry Logic
  • Anlegen von Rechnungen, Kunden und Abonnements über eine REST-API
  • Verarbeiten von Webhooks: Ereignisse können mehrfach zugestellt werden, daher sollte der Empfänger Duplikate erkennen, zum Beispiel über die Ereignis-ID
  • Kommunikation mit Zahlungsdienstleistern, die Idempotenz-Schlüssel häufig unterstützen

Praxisregeln

  • Schlüssel vor dem ersten Versuch erzeugen und mit der Operation speichern
  • Ausreichend zufällige Werte verwenden, zum Beispiel UUIDs
  • Schlüssel nur für identische Anfrageinhalte wiederverwenden. Viele Anbieter lehnen abweichende Inhalte zum selben Schlüssel ab.
  • Beachten, dass gespeicherte Schlüssel meist nur befristet gelten. Prüfen Sie die Dokumentation des jeweiligen Anbieters.

Häufige Fragen

Eine Operation ist idempotent, wenn mehrfaches Ausführen dasselbe Ergebnis hat wie einmaliges. Eine doppelt gesendete Anfrage ändert also nichts mehr.
Er identifiziert eine fachliche Operation eindeutig. Der Server erkennt damit Wiederholungen und führt sie nicht ein zweites Mal aus.
Nein. GET, PUT und DELETE sind per Definition idempotent, POST in der Regel nicht. Deshalb wird bei POST-Anfragen, etwa zum Anlegen einer Zahlung, oft ein Idempotency-Key genutzt.
Ja. Webhooks können mehrfach ankommen. Der Empfänger sollte Ereignisse anhand ihrer ID erkennen und doppelte Verarbeitung vermeiden.

Verwandte Begriffe