Идемпотентность

Записывающие вызовы можно безопасно повторять с Idempotency-Key.

Зачем

Сетевые ошибки и тайм-ауты не дают понять, дошёл ли вызов. С тем же Idempotency-Key повтор вернёт тот же ответ вместо дубликата.

Как

Заголовок Idempotency-Key с уникальным значением (например UUID) на каждую бизнес-операцию, действует 24 часа для ключа.

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

Правила

Тот же ключ + то же содержимое → сохранённый ответ с Idempotent-Replayed: true. Тот же ключ + другое содержимое → 422 idempotency-mismatch. Первый вызов ещё выполняется → 409 с Retry-After. Ответы 429 и 5xx не сохраняются.