Идемпотентность: почему 90% разработчиков делают её неправильно

Идемпотентность: почему 90% разработчиков делают её неправильно

Идемпотентность — это не «повторный запрос не должен сломать API». Это гарантия, что один и тот же бизнес-эффект не выполнится дважды, даже если сеть устроила вам цирк с потерянным ответом и ретраем.

Типовая ошибка №1: idempotency key живёт только в памяти процесса. Процесс упал — ключ испарился, клиент повторил запрос, и вот вам двойное списание. Костыль на костыле и финтехом погоняет.

Типовая ошибка №2: ключ привязан к телу запроса, но не к бизнес-операции. Меняете метаданные — получаете новый «уникальный» запрос и второй холд. Ключ должен склеивать именно payment intent, а не JSON-обёртку вокруг него.

Типовая ошибка №3: хранить только факт «ключ был». Этого мало. Нужен ответ целиком: статус, payment_id, ошибка, время создания. Иначе на повторе вы не знаете, что отдавать клиенту, и устраиваете лотерею вместо контракта. Документация — это ложь, логи — истина.

Правильная схема скучна, как аудит: один ключ, одна транзакционная запись, жёсткий TTL, защита от гонок на уровне БД, и одинаковый ответ на все повторы до окончательного сеттлмента. Идемпотентность или смерть.

Если у вас ключ не переживает рестарт, не переживает повторный webhook и не переживает ретрай клиента — у вас не идемпотентность, а декоративная иллюзия.