Netzwerke fallen an der ungünstigsten Stelle aus: nachdem der Server gehandelt hat, aber bevor Sie die Antwort erhalten. Ein Idempotenzschlüssel macht den Retry sicher.
So funktioniert es
Der Client erzeugt für eine beabsichtigte Aktion einen eindeutigen Schlüssel und sendet ihn mit der Anfrage. Der Server speichert den Schlüssel zusammen mit dem Ergebnis. Kommt derselbe Schlüssel erneut an, spielt der Server das gespeicherte Ergebnis zurück, statt erneut zu handeln.
Die IETF-Arbeitsgruppe HTTPAPI standardisiert das als Request-Header Idempotency-Key (Entwurf 08, Oktober 2026, noch kein RFC). Sie beschreibt den Schlüssel als „a unique value generated by the client which the resource uses to recognize subsequent retries of the same request“ (Übersetzung: „einen eindeutigen, vom Client erzeugten Wert, an dem die Ressource spätere Wiederholungen derselben Anfrage erkennt“) und empfiehlt eine UUID oder eine ähnliche zufällige ID. Die Fehlerfälle des Entwurfs:
| Situation | Status |
|---|---|
| Schlüssel fehlt, obwohl erforderlich | 400 Bad Request |
| Ursprüngliche Anfrage läuft noch | 409 Conflict |
| Schlüssel mit anderem Body wiederverwendet | 422 Unprocessable Content |
Die Builders’ Library von AWS sagt dasselbe aus Client-Sicht: „APIs with side effects aren’t safe to retry unless they provide idempotency.“ (Übersetzung: „APIs mit Nebenwirkungen lassen sich nur dann sicher wiederholen, wenn sie Idempotenz bieten.“)
Warum es wichtig ist
Retries mit exponentiellem Backoff sind gängige Praxis, und viele SDKs wiederholen Anfragen automatisch. Ohne Idempotenz kann ein Retry nach einem Timeout zwei Bestellungen oder zwei Abbuchungen erzeugen. Mit einem Schlüssel ist der Retry sicher, egal was der erste Versuch bewirkt hat. Damit ist er ein zentrales Werkzeug für Agents und Skripte, die ohne menschliche Aufsicht etwas kaufen, buchen oder anlegen.
Bei BroadNet Inference
BroadNet nutzt dieses Muster beim Kauf von Stundenschlüsseln. POST /portal/keys/hourly nimmt eine request_id im JSON-Body entgegen, und die Dokumentation stellt klar: „Idempotency is required for money safety“ (Übersetzung: „Idempotenz ist für die Sicherheit bei Zahlungen erforderlich“):
curl -X POST https://inference.broadnet.ai/portal/keys/hourly \
-H "Authorization: Bearer <portal-credential>" \
-H "Content-Type: application/json" \
-d '{"request_id":"order-20260920-001","label":"kiosk-1"}'
Eine wiederverwendete request_id erzeugt keinen weiteren Schlüssel und bucht nichts erneut ab. Wiederholen Sie die Anfrage nach einem Timeout, einem Verbindungsabbruch, einem 409 mint_in_progress oder einem 5xx mit derselben request_id. Eine Wiederholung liefert already_issued: true und den Alias des Schlüssels; nur die erste erfolgreiche Antwort enthält den eigentlichen Schlüssel. In der Dokumentation heißt es: „Never generate a replacement id until the original result is known.“ (Übersetzung: „Erzeugen Sie niemals eine Ersatz-ID, bevor das ursprüngliche Ergebnis bekannt ist.“)
Für /v1/chat/completions oder Transkriptionen dokumentiert BroadNet keinen Idempotenzschlüssel. Was Sie dort wiederholen sollten, steht unter Fehlercodes und Retries; warum blinde Retries einen 429 verschlimmern können, erklären die Rate Limits.