Що таке ключ ідемпотентності (Idempotency-Key)
Ключ ідемпотентності — унікальний ідентифікатор запиту, який гарантує, що повторне надсилання того самого запиту не створить дубліката операції.
Мережа ненадійна: запит на створення платежу чи виплати може дійти до сервера, а відповідь — загубитися через тайм-аут. Клієнт не знає, чи операція виконана, і повторює запит. Без захисту з’явиться два платежі або, що гірше, дві виплати. Ключ ідемпотентності вирішує це: сервер запам’ятовує ключ і на повторний запит повертає результат першого, нічого не створюючи вдруге.
Підхід популяризував Stripe, а зараз для заголовка Idempotency-Key є проєкт стандарту IETF. Схема проста: клієнт генерує унікальний ключ (наприклад, UUID) для кожної логічної операції і передає його в заголовку. Якщо той самий ключ прийде з іншим тілом запиту, сервер поверне помилку — це захист від випадкового повторного використання.
Головне правило — ключ має відповідати бізнес-операції, а не HTTP-спробі. Наприклад, для виплати можна використати ID заявки на виведення у вашій базі, для платежу — ID замовлення. Тоді навіть після перезапуску сервісу повторна спроба буде з тим самим ключем.
Типові помилки: генерувати новий ключ при кожній спробі (тоді він нічого не захищає); використовувати один ключ для різних операцій; не зберігати ключ і не мати змоги повторити запит після збою; ігнорувати ідемпотентність саме там, де вона найважливіша — на виплатах.
У Moonvex заголовок Idempotency-Key обов’язковий для створення платежів, виплат і підписок, тож дублікати при повторах виключені на рівні API.
Як правильно використовувати ключ
- Один ключ — одна бізнес-операція.
- Будувати ключ з ID замовлення чи заявки або зберігати UUID у базі.
- Повторювати запит з тим самим ключем і тим самим тілом.
- Не використовувати ключ повторно для інших операцій.