Ідемпотентність API: як уникнути дублів операцій

Чому повтори неминучі

У розподіленій системі мережа ненадійна: клієнт надсилає запит на списання коштів, але не отримує відповідь через тайм-аут і, не знаючи, чи виконалася операція, повторює її. Без спеціального захисту це призводить до подвійного списання — класична проблема at-least-once доставки. Детальніше про суміжний підхід можна прочитати в матеріалі «Обробка помилок у розподілених системах».

Idempotency Key на практиці

Стандартний патерн — клієнт генерує унікальний Idempotency-Key для операції один раз і передає його в кожній спробі запиту. Сервер зберігає результат першого виконання за цим ключем і при отриманні дубліката повертає вже готову відповідь, не виконуючи операцію повторно.

POST /payments HTTP/1.1
Idempotency-Key: 7f1c9e2a-91b4-4d3e-9c77-1a2b3c4d5e6f

Важливий нюанс — вікно зберігання ключів не може бути нескінченним, зазвичай це 24–48 годин, а сама перевірка і запис результату повинні бути атомарною операцією, інакше два паралельні повтори все одно проскочать обидва. На рівні бази даних це найчастіше реалізують через унікальний індекс на поле ключа й обробку помилки конфлікту як сигналу «операція вже виконується або виконана». Ці ідеї перегукуються з темами «Патерн Saga для розподілених транзакцій» та «Docker: багатоступеневі збірки для зменшення образів».