Idempotenz

Schreibende Aufrufe sind mit Idempotency-Key gefahrlos wiederholbar.

Warum

Netzfehler und Timeouts lassen offen, ob ein Aufruf angekommen ist. Mit demselben Idempotency-Key bekommst du beim Wiederholen dieselbe Antwort statt eines Duplikats.

So geht es

Header Idempotency-Key mit einem eindeutigen Wert (z. B. UUID) je fachlichem Vorgang, gültig 24 Stunden je Schlüssel.

curl

curl -X POST https://www.claritos.io/api/v1/contacts \
  -H "Authorization: Bearer capi_…" \
  -H "Idempotency-Key: 5c3f9a4e-…" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "PERSON", "firstName": "Anna", "lastName": "Muster" }'

Regeln

Gleicher Key + gleicher Inhalt → gespeicherte Antwort mit Idempotent-Replayed: true. Gleicher Key + anderer Inhalt → 422 idempotency-mismatch. Läuft der erste Aufruf noch → 409 mit Retry-After. Antworten mit 429 oder 5xx werden nicht gemerkt.