Idempotenz und Wiederholungen

Der Weg von der Partneranwendung bis ins lokale Dokumentenmanagement führt über mehrere Stationen. Jede davon kann eine Nachricht vorübergehend verlieren, weshalb überall mindestens einmal zugestellt wird. Damit daraus keine doppelten Importe werden, gibt es den Idempotency-Key.

Das Versprechen lautet: Eine Anfrage mit demselben Schlüssel wird höchstens einmal ausgeführt – ganz gleich, wie oft sie gesendet wird.

Der Schlüssel

POST /v1/dms/documents
Authorization: Bearer eyJ...
Idempotency-Key: import-schriftsatz-2026-0042-001
Content-Type: application/json

Ein Verstoß gegen Zeichensatz oder Länge wird mit 400 abgewiesen – bewusst, damit eine Anwendung, die sich auf Idempotenz verlässt, sofort merkt, dass ihr Schlüssel nicht angenommen wurde.

Als Wert eignet sich eine zufällige Kennung (etwa eine GUID) oder eine aus dem Fachvorgang abgeleitete Zeichenkette. Wichtig ist nur: ein Schlüssel je fachlichem Vorgang, und bei jedem Wiederholungsversuch derselbe.

Was bei einer Wiederholung passiert

Anders als bei manchen anderen Schnittstellen wird das ursprüngliche Ergebnis nicht zwischengespeichert und nicht noch einmal ausgeliefert. Stattdessen meldet die Schnittstelle den Doppelversuch als solchen:

Wichtig für die Umsetzung. Ein 409 IDEMPOTENCY_KEY_REUSED ist kein Fehler des Auftrags. Es sagt nur: „Dieser Auftrag wurde bereits bearbeitet.“ Ob er erfolgreich war, sagt es nicht. Die Anwendung muss den tatsächlichen Ausgang selbst feststellen – bei den Vorgängen mit 202 Accepted über die Vorgangsabfrage GET /v1/platform/operations/{operationId}, sonst über eine fachliche Prüfung (existiert das Dokument bereits in der Zielakte?).

Zwei Fallen, die man kennen sollte

Der Schlüssel kennt den Inhalt der Anfrage nicht

Es wird ausschließlich der Schlüssel ausgewertet, nicht der Anfrageinhalt. Wird derselbe Schlüssel mit einem anderen Inhalt verwendet, gilt das als Wiederholung und wird abgewiesen – der zweite Inhalt wird also nicht stillschweigend ausgeführt, aber der Widerspruch wird auch nicht als solcher gemeldet.

Regel: Ein neuer Auftrag bekommt immer einen neuen Schlüssel. Auch dann, wenn nur ein Feld korrigiert wurde.

Ein Schlüssel taugt nicht als Wiederholung nach einer Korrektur

Schlägt ein Import wegen eines falschen Feldes fehl und wird das Feld korrigiert, dann ist das ein neuer Auftrag. Mit dem alten Schlüssel würde die korrigierte Anfrage als Doppelversuch abgewiesen.

Wiederholungsstrategie

Die Empfehlung nach HTTP-Status:

Retry-After hat immer Vorrang. Nennt die Antwort eine Wartezeit – bei 429 und bei 503 tut sie das –, gilt diese und nicht die Obergrenze aus der Tabelle. Bei TENANT_OVERLOADED sind das zum Beispiel 120 Sekunden.

Diese Seite ist die maßgebliche Quelle für das Wiederholungsverhalten. Die Empfehlungen je Fehlercode in Fehlercodes verweisen darauf; wo beides zu widersprechen scheint, gilt die Empfehlung des konkreten Codes.

Der Zufallsanteil ist kein Detail, sondern wichtig: Ohne ihn treffen alle wartenden Anwendungen gleichzeitig wieder auf, sobald eine Störung endet.

Der Idempotency-Key bleibt über alle Versuche eines Auftrags derselbe.

Der Sonderfall „keine Antwort erhalten“

Das ist der Fall, für den Idempotenz überhaupt existiert: Der Auftrag ist möglicherweise angekommen und ausgeführt worden, nur die Antwort ging verloren. Die Anwendung kann das nicht unterscheiden.

Mit Schlüssel ist der Wiederholungsversuch gefahrlos:

• Der Auftrag kam nicht an → er wird jetzt ausgeführt.
• Der Auftrag kam an und läuft noch → 504 IDEMPOTENCY_KEY_INFLIGHT_TIMEOUT.
• Der Auftrag kam an und ist fertig → 409 IDEMPOTENCY_KEY_REUSED, und die Anwendung klärt den Ausgang über die Vorgangsabfrage.

In keinem der drei Fälle entsteht ein doppeltes Dokument.

Was Idempotenz nicht leistet

• Keine Reihenfolgegarantie. Zwei Aufrufe mit verschiedenen Schlüsseln können in beliebiger Reihenfolge verarbeitet werden. Wer eine Reihenfolge braucht, muss auf eigener Seite serialisieren oder das Ergebnis des ersten Aufrufs als Eingabe für den zweiten verwenden.
• Keine unbegrenzte Gültigkeit. Siehe den folgenden Abschnitt – nach etwa fünf Minuten ist ein Schlüssel verbraucht.
• Keine Umwandlung eines nicht wiederholbaren Vorgangs. Idempotenz schützt vor doppelter Ausführung, nicht vor einem fachlich falschen Auftrag.

Wie lange ein Schlüssel wirkt

Ein Schlüssel wird rund fünf Minuten vorgehalten. Danach ist er der Schnittstelle unbekannt.

Das ist die wichtigste Zahl auf dieser Seite, denn die Folge ist unangenehm: Ein Wiederholungsversuch nach Ablauf dieser Frist wird ganz normal ausgeführt – er gilt nicht mehr als Wiederholung. Bei einem Import entsteht dadurch ein zweites Dokument.

Daraus folgen zwei Regeln:

• Alle Wiederholungsversuche eines Auftrags innerhalb weniger Minuten abschließen. Die in der Tabelle oben empfohlene Obergrenze von etwa zehn Minuten ist bereits zu lang, um sich am Ende noch auf Idempotenz verlassen zu können.
• Nach einer längeren Unterbrechung nicht blind wiederholen. Wer einen Auftrag erst Stunden später erneut aufnimmt – etwa nach einem Neustart der eigenen Anwendung –, muss vorher fachlich prüfen, ob er bereits ausgeführt wurde. Bei einem Import heißt das: die Dokumente der Zielakte auflisten und nachsehen.

Korrelationskennung mitgeben

Unabhängig vom Idempotenzschlüssel sollte jeder Aufruf eine eigene Korrelationskennung tragen:

X-Correlation-Id: 9f3a2b7c4d1e5081

Erlaubt sind Buchstaben, Ziffern sowie ., _ und -, bis zu 64 Zeichen. Wird keine oder eine unzulässige Kennung geschickt, erzeugt die Schnittstelle selbst eine.

Wo die Kennung in der Antwort steht, hängt vom Ausgang ab:

Der Grund ist technischer Natur: Die Fehlerbehandlung setzt die Antwort neu auf und verwirft dabei bereits gesetzte Kopfzeilen. Für eine Integration heißt das: Im Fehlerfall die Kennung aus dem Antwortkörper lesen, nicht aus der Kopfzeile. Wer sich auf die Kopfzeile verlässt, steht ausgerechnet dann ohne Kennung da, wenn er sie braucht.

Diese Kennung ist der rote Faden durch alle Protokolle bis in die Kanzlei hinein. Sie gehört in das Protokoll der Partneranwendung, damit sie bei einer Rückfrage zur Hand ist.

Weiterführend

• Fehlercodes
• Schnellstart