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), siehe Fehler und Durchsatzbegrenzung.
Status 409: die Sekunden aus Retry-After abwarten, dann mit demselben Key wiederholen.
Andere 4xx-Fehler: zuerst den Request korrigieren und dann mit einem neuen Key senden; der geänderte Request würde sonst mit 422 abgelehnt.

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.
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.