Идемпотентные ключи: как не списать деньги с клиента дважды

Сетевой таймаут не означает, что запрос не выполнился на сервере — он мог выполниться, а ответ просто не дошёл до клиента. Идемпотентные ключи решают эту неоднозначность.

Проблема повторной отправки

Клиент отправляет запрос на списание средств. Сеть обрывается до получения ответа. Клиент, не зная, выполнился ли запрос, повторяет его. Без защиты сервер выполнит операцию дважды.

Как работает идемпотентный ключ

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

Время жизни ключа

Ключи обычно хранятся 24 часа — этого достаточно, чтобы покрыть разумные сценарии повторов, но не создавать неограниченно растущее хранилище. В Hexly срок хранения настраивается на уровне проекта.

Где это особенно важно

Любые операции с побочными эффектами: платежи, отправка email, создание заказов, списание остатков на складе. Для чисто читающих GET-запросов идемпотентность обеспечивается самой природой операции и отдельного ключа не требует.

Пример заголовка

curl -X POST https://api.hexly.dev/v1/payments \
  -H "Idempotency-Key: 8f14e45f-ceea-4b19" \
  -H "Authorization: Bearer hx_live_..." \
  -d '{{"amount": 4200}}'