Таймаут клиента не означает отмену работы сервера. Ответ мог потеряться после COMMIT, а повторный POST создаёт второй заказ. Поэтому retry должен повторять идентичность первой попытки, а не только её URL и body.

Клиент генерирует idempotency key при нажатии «Создать» и сохраняет до получения окончательного результата. Новый ключ появляется только для нового намерения пользователя. Сервер связывает ключ с владельцем, операцией и hash нормализованных параметров.

Ответ зависит от состояния первого запроса

Запись ключаПовтор с тем же payloadПовтор с другим payload
НетЗарезервировать и выполнитьЗарезервировать как новую первую попытку
pendingВернуть 202/текущий статус или ждать ограниченноОтклонить конфликт
completedВернуть сохранённый результатОтклонить reuse ключа
failed retryableПовторить по явной политикеОтклонить конфликт
failed finalВернуть тот же финальный отказОтклонить конфликт

Конкретные HTTP status выбираются контрактом API. Неизменный принцип: один ключ нельзя тихо привязать к другой сумме, корзине или получателю. AWS для client token и Stripe для idempotency key также описывают ошибку/защиту при повторе с изменёнными параметрами.

Резервирование и side effect связываются атомарно

BEGIN;
INSERT INTO idempotency_keys(scope, operation, idem_key, request_hash, status)
VALUES (:account, :operation, :key, :hash, 'pending')
ON CONFLICT (scope, operation, idem_key) DO NOTHING;

-- Если вставка выполнена, создаём бизнес-запись в той же транзакции.
INSERT INTO orders(id, account_id, amount, status)
VALUES (:order_id, :account, :amount, 'created');

UPDATE idempotency_keys
SET status = 'completed', resource_id = :order_id, response_code = 201
WHERE scope = :account AND operation = :operation AND idem_key = :key;
COMMIT;

Это условный SQL: ветка конфликта обязана прочитать существующую запись и сравнить hash до выполнения INSERT orders. Если side effect находится во внешней системе, одной локальной транзакции мало — используйте outbox/state machine и собственный idempotency key внешнего провайдера.

Ключ имеет область и срок жизни

Глобальный unique по короткой случайной строке неудобен для нескольких клиентов. Практичная область — account/tenant + endpoint или тип операции + key. Срок хранения должен покрывать максимальное окно сетевых и очередных повторов; после удаления старого ключа тот же retry снова становится новой операцией.

  • Ключ не содержит email, телефон, номер карты или другой чувствительный идентификатор.
  • Одинаковый key с другим request hash блокируется.
  • Логи показывают hash/key reference, но не полный body.
  • TTL измеряется от финального состояния по выбранному контракту.
  • Клиент не генерирует новый key при каждом автоматическом retry.

HTTP-метод сам по себе не спасает POST

RFC 9110 определяет idempotent method через одинаковый предполагаемый эффект нескольких идентичных запросов; PUT и DELETE имеют идемпотентную семантику, POST — не автоматически. Даже с PUT нужно выбрать стабильный resource ID, иначе клиентский retry всё равно попадёт в другой ресурс.

Гонку проверяем двумя одновременными запросами

  1. Отправить два POST одновременно с одним key и одинаковым body.
  2. Убедиться, что создана одна бизнес-запись и ответы указывают на неё.
  3. Повторить key с другой суммой и получить явный конфликт.
  4. Оборвать соединение после серверного COMMIT и повторить запрос.
  5. Перезапустить worker при status=pending и восстановить операцию по state machine.
  6. Проверить retry после истечения TTL согласно опубликованному контракту.

Существующие дубли исправляются отдельно

Idempotency предотвращает новые повторы, но не говорит, какой из двух старых заказов отменить. Для восстановления сопоставьте account, client operation reference, время, сумму и downstream effects. Возврат денег, отмена доставки или удаление задачи выполняются отдельным контролируемым процессом с собственным аудитом.

Минимум данных для диагностики

Подготовьте request IDs обеих попыток, обезличенный idempotency key, request hash, timestamps, момент COMMIT и созданные resource IDs. Не прикладывайте authorization header и полный payload. Этого достаточно, чтобы найти разрыв между reservation, side effect и сохранением ответа.

Проверенные источники