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

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

Идемпотентность — это не «поставили idempotency-key и забыли». Это контракт: один и тот же запрос должен давать один и тот же результат, даже если клиент умер, вебхук пришёл дважды, а retry-логика ушла в истерику.

Типовая ошибка №1: хранят ключ, но не состояние операции. В итоге один запрос создал платёж, второй увидел key и вернул «ок», хотя сеттлмент ещё не случился. Это не идемпотентность, а косплей на неё. Нужен дедуп по ключу + привязка к финальному статусу: pending, authorized, captured, failed.

Ошибка №2: делают ключ уникальным только на входе, а потом забывают про боковые эффекты. Комиссия списалась дважды, холд повис, вебхук улетел повторно — и ваш бэкенд разводит руками. Документация — это ложь, логи — истина. Смотрите не только ответ API, но и все побочные записи в платёжном контуре.

Ошибка №3: смешивают идемпотентность с безопасностью. Ключ — это не секрет и не защита от мошенника. Он нужен для повторов, а не для того, чтобы клиент «не мог нажать дважды». Если у вас нет нормальной транзакционной границы и блокировок на критических шагах, получите дубль на ровном месте.

Правильная схема скучна: один бизнес-ключ, атомарная запись результата, TTL на дедуп-таблицу, повторяемые ответы по одному и тому же payload, и отдельная логика для асинхронных статусов. Идемпотентность или смерть.