Idempotenz

Netzwerke verlieren Antworten. Damit du einen POST nach Timeout oder Verbindungsabbruch gefahrlos wiederholen kannst, akzeptieren alle POST-Routen der API den Header Idempotency-Key.

POST /api/v1/documents/create-and-send HTTP/1.1
Authorization: Bearer ratum_live_…
Idempotency-Key: 4f9c2a7e-1b3d-4c8e-9f1a-2b3c4d5e6f70
Content-Type: application/json

Pflicht ist er bei POST /documents/create-and-send und POST /documents/{id}/send. Ohne Key antworten diese Routen mit 400 idempotency_key_required. Bei allen anderen POST-Routen ist er optional, aber empfohlen.

Regeln

• Ein Key ist 1–255 druckbare ASCII-Zeichen lang. Am einfachsten nimmst du eine UUID v4 pro logischer Operation, also nicht pro HTTP-Versuch.
• Erzeuge den Key vor dem ersten Versuch und verwende ihn für alle Wiederholungen dieser Operation.
• Erfolgreiche Antworten (2xx) speichert ratum 24 Stunden pro API-Key. Eine Wiederholung liefert die gespeicherte Antwort, ohne die Operation erneut auszuführen. Solche Antworten tragen den Header Idempotent-Replayed: true.
• Fehlerantworten werden nicht gespeichert. Nach z. B. 409 not_ready oder 429 kannst du mit demselben Key erneut versuchen.

Fehler

Code	Bedeutung	Reaktion
idempotency_key_required (400)	Route verlangt den Header	Key mitschicken
idempotency_key_invalid (400)	leer, länger als 255 oder Nicht-ASCII	gültigen Key erzeugen
idempotency_key_reused (422)	gleicher Key, aber andere Route oder anderer Body	neuen Key für die neue Operation
idempotency_key_in_use (409)	die erste Anfrage mit diesem Key läuft noch	Retry-After (1 s) abwarten, dann mit demselben Key wiederholen

Retry-Strategie

versuch = 0
key = neue UUID
wiederhole:
  antwort = POST(..., Idempotency-Key: key)
  2xx                     → fertig
  429                     → Retry-After abwarten, nochmal
  409 idempotency_key_in_use, 5xx, Timeout → exponentiell warten (1 s, 2 s, 4 s …), nochmal
  sonst (4xx)             → nicht wiederholen, Fehler behandeln

Unabhängig vom Header verhindert ratum doppelten Versand auch auf Datenbankebene: Ein bestehendes Dokument wird nie zweimal versendet. Ob createAndSend bei einer Wiederholung ein zweites Dokument anlegt, verhindert dagegen nur derselbe Idempotency-Key.