Erklärer · Entwicklung

Was ist ein Idempotency-Key, und warum Ihre App einen braucht

4. November 2026 · Software by Design

Jede offline-fähige App muss früher oder später dieselbe Frage beantworten: Was passiert, wenn die Nutzerin zweimal auf „Senden“ tippt oder das Netz mitten in der Anfrage abreißt und der Client sie wiederholt? Die Antwort ist ein kleiner Mechanismus namens Idempotency-Key. Wie er funktioniert und wie er in unserem eigenen Code aussieht, steht hier.

Das Problem in einem Satz

Netzwerke sind unzuverlässig. Clients senden ihre Anfragen deshalb erneut, und schon kommt dieselbe logische Aktion mehrfach an. Ohne Schutz werden daraus zwei Zeiteinträge, zwei Rechnungen, zwei Buchungen.

Beachten Sie, was das Problem nicht ist: Es ist nicht „die Nutzerin hat doppelt geklickt“. Das kommt zwar auch vor, aber der Normalfall ist unsichtbarer: Eine mobile App auf der Baustelle verliert den Empfang, stellt das Einstempeln in die Warteschlange, der Server verarbeitet es, die Antwort geht unterwegs verloren, und die App sendet es, völlig korrekt, noch einmal. Das Duplikat ist kein Fehler, sondern das System, das exakt so arbeitet wie vorgesehen.

Der Mechanismus

Ein Idempotency-Key ist eine eindeutige Kennung, die der Client pro logischer Aktion erzeugt, nicht pro HTTP-Request. Der Client hängt denselben Schlüssel an die erste Anfrage und an jeden Retry dieser Aktion. Der Server führt Buch über die Schlüssel, die er gesehen hat. Kommt ein Schlüssel zweimal an, liefert er das erste Ergebnis, statt die Mutation noch einmal auszuführen.

Drei Eigenschaften machen es möglich:

  • Der Client besitzt den Schlüssel. Würde der Server ihn ausstellen, ließe sich ein Retry vor dessen Empfang nicht zuordnen. Der Schlüssel entsteht auf dem Gerät: In unseren mobilen Apps ist das eine UUID, die in dem Moment erzeugt wird, in dem die Arbeitskraft stempelt, nicht erst beim Netzwerkcall.
  • Der Eintrag ist ein Claim, kein Ergebnis. Der Server schreibt zuerst den Claim („dieser Schlüssel gehört jetzt mir, Ergebnis ausstehend“) und ändert danach erst den Zustand. Ein konkurrierender Retry findet den Claim vor und wartet auf das erste Ergebnis oder spielt es erneut ab. Eine zweite Mutation kommt so nie dazwischen.
  • Der Claim bindet die Payload. Wir speichern zum Schlüssel einen Hash der Aktion und ihrer normalisierten Eingaben. Gleicher Schlüssel bei anderer Payload heißt 409-Konflikt statt stiller Überschreibung. Ein Retry darf immer nur „dasselbe noch einmal“ bedeuten.

Wo er in unseren Apps auftaucht

Die mobile Stempel-Warteschlange von ArbeitszeitCheck trägt eine clientRequestId durch jedes Replay. TourCheck bindet denselben Vertrag an client_event_id bei Kontrollpunkt-Bestätigungen: Dort vergleicht ein Replay den gesamten Claim, also Notiz, Foto und Zeitstempel, mit der gespeicherten Zeile. Das Ablaufdatum ist genauso wichtig wie die Deduplizierung. Unsere Claim-Zeilen leben sieben Tage: lang genug für ein langes Wochenende ohne Empfang, kurz genug, damit die Tabelle eine Warteschlange bleibt und kein Log wird.

Die Kurzfassung für Ihre eigene App

Wenn Ihre API Zustand verändert und Ihr Client Anfragen wiederholen kann (und das kann jeder Client), brauchen Sie genau drei Dinge: einen clientseitig erzeugten Schlüssel pro Aktion, eine Claim-Zeile beim ersten Schreiben und einen Payload-Hash, damit „gleicher Schlüssel“ auch „gleiche Absicht“ heißt. Das ist das ganze Muster. Alles andere, also Replay-Fenster, Aufräumjobs und Konflikt-Statuscodes, ist nur Rohrleitung um diese drei Zusagen.