Идемпотентность HTTP-запросов: как проверить, что повторный запрос не создаёт второй заказ
Checkcraft — программа для проверки API и логов без кода, есть бесплатная версия. Скачать без регистрации →
Платёжная песочница присылает уведомление дважды, клиент жмёт «Оплатить» второй раз, сеть рвётся и запрос повторяется. Если API не идемпотентен, появляется второй платёж или второй заказ. Разберём, что это значит и как это проверить.
Что такое идемпотентность
Запрос идемпотентен, если повторить его несколько раз — то же самое, что выполнить один раз: результат на сервере не меняется. По RFC 9110 идемпотентны PUT, DELETE и безопасные методы GET, HEAD, OPTIONS, TRACE. POST и PATCH по определению не идемпотентны, поэтому для создания платежей и заказов API добавляют ключ идемпотентности.
Ключ идемпотентности
Клиент передаёт в заголовке уникальное значение для операции. Например, в ЮKassa это заголовок Idempotence-Key: значение уникально для операции на стороне магазина. Получив запрос с уже известным ключом, сервер возвращает результат первой операции, а не выполняет её заново.
Как проверить
Отправьте один и тот же запрос дважды с одним ключом и сравните ответы: идентификатор платежа должен совпасть. Затем проверьте последствия, а не только ответ: в базе одна запись, в логах по traceId одно событие «создан». Новый ключ должен давать новую операцию. Отдельно проверьте запрос без ключа и повтор с тем же ключом, но другим телом — что делает ваш API, решают требования.
# 1. Тот же запрос дважды с одним ключом
POST /payments Idempotence-Key: 7f3a… → 200, payment_id = P1
POST /payments Idempotence-Key: 7f3a… → 200, payment_id = P1 (тот же!)
# 2. Проверить последствия, а не только ответ
SELECT count(*) FROM payments WHERE order_id = 5001; -- ожидаем 1
в логах по traceId — одна запись «payment created», а не две
# 3. Новый ключ — новая операция
POST /payments Idempotence-Key: 9b1c… → новый payment_idПочему одного ответа мало
Оба ответа могут прийти со статусом 200 и одинаковыми полями, а в базе окажется две строки. Поэтому повторный запрос проверяют по трём источникам: ответ, лог по traceId и запись в базе. В Checkcraft это одна проверка: запрос, поиск записей в Kibana по traceId и SELECT в базе (база — в Pro).
Повторите это на своём API
Checkcraft — настольная программа: сохраняет проверки ответа API без кода и показывает, что не совпало. Начните с учебного примера, затем подставьте свои обезличенные данные. Free работает на Windows и Linux без ограничения срока.
Скачать FreeКак получить и запустить приложениеСкачивание без регистрации и почты, архив готов за пару минут. Состав бесплатной версии опубликован на странице тарифов.
Документация
RFC 9110: идемпотентные методы · ЮKassa: формат взаимодействия и Idempotence-Key
Начните с примера по ссылкам и сопоставьте результат с требованием своей проверки.