Личный кабинет

Главная → Документация → Idempotency-Key

Idempotency-Key: защита от двойного списания

Заголовок Idempotency-Key защищает от двойного списания при повторе запроса. Если ответ не дошёл из-за обрыва связи или таймаута, повторите запрос с тем же ключом: сервер вернёт сохранённый ответ и не выполнит проверку второй раз.

Работает на всех методахПовтор без списанияКлюч действует 24 часа

Как пользоваться

Придумайте ключ на своей стороне, один на одну операцию: номер заказа, номер заявки или случайный 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.

Что запоминается

Сводный отчёт

В методе /report один ключ значит один отчёт: повтор создания с тем же ключом возвращает тот же отчёт в его текущем состоянии. Новый отчёт не создаётся, блоки второй раз не запускаются.

Рекомендации

Вопросы и ответы

Обязательно ли передавать ключ?

Нет. Без заголовка всё работает как раньше.

Сколько живёт ключ?

24 часа с первого запроса. После этого тот же ключ считается новым.

Виден ли повтор в истории запросов?

Нет: повтор по ключу не создаёт новой строки и не меняет баланс. В ответе остаётся requestId первого запроса.