Idempotency

Write calls can be safely retried with Idempotency-Key.

Why

Network errors and timeouts leave it open whether a call arrived. With the same Idempotency-Key a retry returns the same response instead of a duplicate.

How

Header Idempotency-Key with a unique value (e.g. UUID) per business operation, valid 24 hours per key.

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" }'

Rules

Same key + same payload → stored response with Idempotent-Replayed: true. Same key + different payload → 422 idempotency-mismatch. First call still running → 409 with Retry-After. Responses with 429 or 5xx are not stored.