Idempotente Requests

Ein Timeout oder Verbindungsfehler verrät nicht, ob der Request ausgeführt wurde. Ein GET lässt sich immer gefahrlos wiederholen, ein blind wiederholter POST kann dieselbe Ressource aber doppelt anlegen. Idempotency-Keys lösen das: Sie machen POST-Requests sicher wiederholbar.

So funktioniert es

Senden Sie den HTTP-Header Idempotency-Key mit einem frei gewählten Wert (1 bis 200 Zeichen, z. B. eine UUID) an einen beliebigen POST-Endpunkt:

curl "https://api.schulungstool.de/v1/participations/" \
  -H "Authorization: Token <API-Schlüssel>" \
  -H "Idempotency-Key: a7fbbb17-5f16-4cbd-9942-ad9b4c4a3c34" \
  -H "Content-Type: application/json" \
  -d '{"user": "4bcb84b8-6bc5-48f4-a15e-d87e056bd01c", "course": "06285ae7-38a0-484a-b779-b11490c706c0", "due_date": "2027-01-31"}'

Der erste Request wird normal ausgeführt. Ist er erfolgreich (Status 2xx), wird die Antwort 24 Stunden gespeichert. Senden Sie denselben Request mit demselben Key erneut, führt die API ihn nicht noch einmal aus, sondern liefert die gespeicherte Antwort, byte-identisch und markiert mit dem HTTP-Header Idempotent-Replayed: true.

Nur Erfolge verbrauchen einen Key. Scheitert ein Request (Status 4xx oder 5xx), wird der Key wieder freigegeben und der nächste Request damit normal ausgeführt.

Keys wählen

Erzeugen Sie für jede neue Operation einen frischen Zufallswert (z. B. eine UUIDv4).
Verwenden Sie exakt denselben Key nur, um exakt denselben Request zu wiederholen.
Keys gelten je API-Schlüssel: Zwei Ihrer API-Schlüssel sehen die Keys des jeweils anderen nie.

Fehlerantworten

Ein Key gehört zu genau einem Request. Die API vergleicht die HTTP-Methode, den Pfad inklusive Query-String, den Content-Type-Header und den rohen Request-Body:

Status	Typ	Situation
`400`	`IdempotencyKeyInvalidError`	Der Key ist leer oder länger als 200 Zeichen.
`409`	`IdempotencyKeyInUseError`	Der erste Request mit diesem Key läuft noch. Die Antwort trägt `Retry-After` mit der Wartezeit in Sekunden.
`422`	`IdempotencyKeyReuseError`	Der Key wurde bereits für einen anderen Request verwendet. Verwenden Sie einen neuen Key.

Empfehlungen für Wiederholungen

Timeout oder Verbindungsfehler: mit demselben Key wiederholen; genau dafür gibt es Idempotency-Keys.
Status 429 oder 5xx: mit demselben Key wiederholen (bei 429 die Sekunden aus Retry-After abwarten, bei 5xx mit exponentiellem Backoff; in beiden Fällen eine kleine zufällige Verzögerung ergänzen, damit nicht viele Clients im selben Moment wiederholen), siehe Fehler und Durchsatzbegrenzung.
Status 409: die Sekunden aus Retry-After abwarten, dann mit demselben Key wiederholen. Wechseln Sie hier nicht auf einen neuen Key: Der erste Request kann noch erfolgreich abschließen, und ein neuer Key würde die Operation ein zweites Mal ausführen.
Andere 4xx-Fehler: zuerst den Request korrigieren und dann erneut senden. Ein Request, der mit einer Fehlerantwort endet, verbraucht seinen Key nicht; der korrigierte Request wird deshalb normal ausgeführt, mit demselben oder einem neuen Key.

Hinweise

Auf GET, PUT, PATCH und DELETE wird der Header ignoriert: Diese Methoden sind bereits idempotent.
Keys laufen nach 24 Stunden ab; danach gilt derselbe Key als neu. Wiederholen Sie deshalb innerhalb dieser 24 Stunden. Ist der Ausgang eines Requests danach noch unklar, prüfen Sie zuerst per GET, ob die Ressource angelegt wurde, bevor Sie den Request erneut senden, egal mit welchem Key.
Ausnahme: POST /v1/users/{id}/login-link/ speichert und wiederholt nie, weil der erzeugte Link nach 30 Sekunden abläuft. Der Header wird trotzdem validiert, und ein anderswo verwendeter Key wird mit 422 abgelehnt.