Что это
Аудитор ключей идемпотентности. Он прогоняет запросы из лога по правилам, которым следует правильный API, и записывает каждый как первую запись, безопасный повтор или проблему.
Аудит идемпотентности для платёжных API и API заказов
Найдите запросы, за которые API списал деньги дважды.
Idempotency Ledger читает логи запросов, записывает каждую операцию записи под её ключом идемпотентности и показывает, где повтор создал второе списание, второй заказ или вторую выплату. Для каждой проблемы указаны сумма под угрозой и способ исправления.
Списания по ключамNo. 0417
| Время | Ключ | Сумма |
|---|---|---|
| 10:00:00 | ik_7f3a | 49.99 |
| 10:00:03 | ik_7f3a | 49.99 |
| 10:05:00 | ik_c044 | 89.00 |
| 10:05:00 | ik_c044 | 89.00 |
| 10:12:00 | ik_f611 | 9.99 |
Лишние списания+89.00 EUR
Для кого
Для бэкенд и платёжных инженеров, SRE и руководителей поддержки, которым нужно понять, действительно ли с клиента списали деньги дважды и почему.
Какую проблему решает
Повторы запросов нормальны, но повтор, который снова выполняет работу, создаёт реальные денежные проблемы. В логах они теряются среди тысяч строк. Книга поднимает их наверх вместе с итогами.
Проверьте лог запросов
Вставьте или откройте выгрузку лога. Ничего не загружается на сервер: разбор и проверки идут на этой странице.
Один запрос на строку, массив JSON или CSV со строкой заголовков.
Поля находятся по названию: time или ts, method, path или url, status, ключ идемпотентности, идентификатор созданного объекта, например charge_id или order_id, amount, currency и customer. Вложенный JSON и заголовки Idempotency-Key тоже поддерживаются.
Здесь появится результат
Вставьте лог и нажмите «Проверить лог» или загрузите пример, чтобы увидеть все виды находок.
Что отмечает книга
Каждый повторяющийся ключ проверяется по порядку времени и сравнивается с тем, что должен был сделать правильный сервер.
Двойной эффект
Тот же ключ, тот же запрос и два разных созданных идентификатора. Сервер выполнил работу дважды. Это самое дорогое.
Гонка
Две копии пришли в пределах двух секунд, и обе прошли успешно. Часто бывает при двойном клике и агрессивных повторах клиента.
Несовпадение тела
Старый ключ пришёл с новыми параметрами. Правильный сервер отказывает с кодом 422. Если принять такой запрос, ошибки клиента останутся скрытыми.
Частичный сбой
Ответ 5xx, после которого объект всё равно создан, а затем повтор, создавший ещё один. Видно только если в логах есть идентификаторы.
Нет ключа
Записи без ключа нельзя дедуплицировать. Две одинаковые записи подряд за короткое время отмечаются как дубль.
Просроченный ключ
Ключ, вернувшийся после окна, считается новой работой. Выберите окно, как на вашем сервере.
Как пользоваться
Выгрузите лог
Возьмите запросы к одному эндпоинту или сервису за период из логов шлюза, балансировщика или приложения.
Вставьте или откройте
Подходят строки JSON, массив JSON, CSV с заголовками или обычные строки с парами key=value.
Задайте срок ключей
Укажите, сколько ваш сервер хранит ключи. API в стиле Stripe хранят их 24 часа.
Прочитайте книгу
Проблемы идут первыми вместе с суммой под угрозой. Откройте ключ, чтобы увидеть каждую строку и исправление, затем скопируйте отчёт или скачайте CSV.
Полезно знать
- Двойной эффект доказывается только если в логе есть идентификатор созданного объекта. Без идентификаторов повторы считаются корректными.
- Запросы сравниваются по методу, пути и телу, а если тела нет, то по сумме, валюте и клиенту.
- Время показано в UTC, а время без часового пояса тоже считается UTC. Строки без времени сохраняют порядок файла.
- Большие логи тоже работают, но для быстрой проверки оставьте только нужные эндпоинты.
- Данные не покидают браузер. И всё же перед тем как делиться отчётом, удалите номера карт и персональные данные.
Вопросы
Что такое ключ идемпотентности?
Уникальное значение, которое клиент отправляет вместе с запросом на запись. Если тот же запрос придёт снова с тем же ключом, сервер вернёт первый результат, а не выполнит работу второй раз.
Почему 409 считается верным ответом?
Это значит, что вторая копия пришла, пока первая ещё выполнялась, и сервер отказался запускать их параллельно. Клиент может повторить позже и получить сохранённый результат.
Почему важно несовпадение тела, если списание было одно?
Если сервер принимает новые параметры под старым ключом, значит у клиента есть ошибка с повторным использованием ключей. В следующий раз она создаст неверное списание, похожее на повтор.
Нужны ли идентификаторы в логах?
С ними проверка становится точной. Записывайте в лог идентификатор объекта, созданного каждой записью, например charge_id или order_id.