Главная → Документация → Idempotency-Key
Idempotency-Key: защита от двойного списания
Заголовок Idempotency-Key защищает от двойного списания при повторе запроса. Если ответ не дошёл из-за обрыва связи или таймаута, повторите запрос с тем же ключом: сервер вернёт сохранённый ответ и не выполнит проверку второй раз.
Как пользоваться
Придумайте ключ на своей стороне, один на одну операцию: номер заказа, номер заявки или случайный UUID. Передайте его заголовком:
curl "https://api.avtovincod.ru/pledge?vin=XTA210990Y1234567" \ -H "Authorization: Bearer ВАШ_ТОКЕН" \ -H "Idempotency-Key: order-12345-pledge"
Если заголовок задать неудобно, ключ можно передать параметром idempotency_key. Ключ: от 8 до 128 знаков, латинские буквы, цифры и знаки _ . : -.
Что происходит при повторе
| Ситуация | Ответ |
|---|---|
| Первый запрос с ключом | Выполняется как обычно. |
| Повтор с тем же ключом и теми же параметрами, первый запрос завершён | Тот же ответ, что в первый раз, с заголовком Idempotent-Replayed: true. Проверка не выполняется, деньги не списываются. |
| Повтор, пока первый запрос ещё выполняется | 409 IDEMPOTENCY_IN_PROGRESS и заголовок Retry-After. Повторите через указанное число секунд. |
| Тот же ключ, но другой метод или другие параметры | 422 IDEMPOTENCY_KEY_REUSED. Для новой операции нужен новый ключ. |
| Ключ неверного вида | 400 IDEMPOTENCY_KEY_INVALID. |
Что запоминается
- Запоминаются итоговые ответы: успешные и те, за которые прошло списание.
- Ответы с ошибкой без списания не запоминаются: повтор с тем же ключом выполнит запрос заново. Это удобно, если источник временно не ответил.
- У методов с опросом (заказ, затем
taskId) промежуточный ответ «ещё выполняется» не запоминается: повтор продолжит ту же задачу. - Ключ привязан к вашему аккаунту: ключи разных клиентов не пересекаются. Все токены одного аккаунта делят ключи между собой.
Сводный отчёт
В методе /report один ключ значит один отчёт: повтор создания с тем же ключом возвращает тот же отчёт в его текущем состоянии. Новый отчёт не создаётся, блоки второй раз не запускаются.
Рекомендации
- Ключ создавайте до первого запроса и храните вместе с операцией, а не генерируйте заново при повторе.
- Повторяйте запрос при обрыве связи, таймауте и ответах
5xx. При ответе409ждите время изRetry-After. - Для разных методов по одной машине используйте разные ключи, например
order-12345-pledgeиorder-12345-taxi.
Вопросы и ответы
Обязательно ли передавать ключ?
Нет. Без заголовка всё работает как раньше.
Сколько живёт ключ?
24 часа с первого запроса. После этого тот же ключ считается новым.
Виден ли повтор в истории запросов?
Нет: повтор по ключу не создаёт новой строки и не меняет баланс. В ответе остаётся requestId первого запроса.