В контексте API идемпотентность означает, что многократные запросы обрабатываются так же, как однократные: получив повторный запрос с теми же параметрами, API вернёт результат исходного запроса, а не создаст новую сущность. Такое поведение помогает избежать нежелательного дублирования операций. Например, если при создании платежа возникли проблемы с сетью и соединение прервалось, вы можете безопасно повторить запрос. POST запросы по умолчанию не идемпотентны, поэтому для них используется заголовок Idempotency-Key. 
Idempotency-Key: 7c3b1f0a-9d2e-4a51-8b6c-1f2e3d4c5b6a

​
Как это работает

  • Ключ — произвольная уникальная строка, которую генерирует клиент на каждую логическую операцию. Рекомендуем использовать UUID v4.
  • Ключ привязан к конкретному проекту и endpoint`y и действует 30 минут, после чего повторный запрос будет обработан как новый.
  • Повторный запрос с тем же ключом и тем же телом вернёт сохранённый ответ — новая сущность не создаётся. В этом случае ответ содержит заголовок X-Idempotency-Replay: true.

​
Конфликты

При конфликте по Idempotency-Key приходит 409 с одним из двух кодов:
  1. idempotency_key_reused — тот же ключ использован с другим телом запроса.
  2. idempotency_in_progress — первый запрос с этим ключом ещё обрабатывается (повтор пришёл слишком рано).
Один ключ — одна логическая операция. Не переиспользуйте ключ для разных платежей и генерируйте новый при каждом новом намерении создать платёж или возврат.

​
Пример

curl https://api.parserpay.io/v1/payments \
  -X POST \
  -H "Authorization: Bearer <project_id>:<api_key>" \
  -H "Idempotency-Key: 7c3b1f0a-9d2e-4a51-8b6c-1f2e3d4c5b6a" \
  -H "Content-Type: application/json" \
  -d '{ "amount": "100.00", "currency": "RUB" }'