В распределённых системах запрос может не дойти, ответ может потеряться, клиент может словить timeout и отправить тот же запрос ещё раз.
Если API не готов к такому сценарию, начинаются дубли: два платежа, два заказа, две записи в базе.
Idempotency решает эту проблему.
Идемпотентная операция может быть вызвана несколько раз, но состояние системы после первого успешного запроса уже не меняется.
Типичный пример: клиент создаёт уникальный ключ операции и отправляет его в заголовке, например:
Idempotency-Key: 8f7a2c9e-12a4-4f8b-91c2
Сервер проверяет этот ключ.
Если ключ новый, он выполняет операцию и сохраняет результат.
Если ключ уже был, сервер не запускает операцию повторно, а возвращает сохранённый ответ.
Так API нормально переживает повторы, сетевые сбои и retries без случайных дублей.
Особенно важно для платежей, создания заказов, бронирований и любых операций, где повторный запрос может стоить денег.