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

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

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

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

Ошибка №2: ключ привязан к телу запроса «примерно». Сегодня сумма 1000, завтра 1000.00, послезавтра порядок полей другой — и у вас уже новый «уникальный» платёж. Ключ должен матчить не строку JSON, а бизнес-операцию: мерчант, amount, currency, purpose, window.

Ошибка №3: идемпотентность путают с дедупликацией вебхуков. Это разные звери. Вебхук может прилететь трижды, но ваш create payment не должен создаваться трижды. И наоборот: один и тот же платёж может породить несколько событий, и это нормально, если статус-машина не ломается.

Запомните простое правило: храните ключ вместе с финальным состоянием и результатом, задавайте TTL на окно ретраев, а при конфликте возвращайте тот же ответ, а не новый «успешный» объект. Идемпотентность или смерть.