Одна операция — один ключ
POST /orders требует заголовок Idempotency-Key: 16–80 символов из A–Z, a–z, 0–9, _ и -. UUID подходит. Ключ уникален в пределах аккаунта и не меняется при перевыпуске API-ключа.
Запишите ключ и точные параметры service, country, maxPrice в свою БД до отправки запроса. После сбоя процесса восстановите их из БД. Не генерируйте UUID внутри функции, которая автоматически повторяется.
Матрица решений
| Результат | Действие |
|---|---|
| 200 + order | Сохраните заказ. Не отправляйте новую покупку. |
| Таймаут / сеть / 5xx | Результат неизвестен. История → повтор с тем же ключом и телом. |
| 409 + pending: true | Операция не завершена. Новый ключ запрещён для обхода ожидания. |
| 409, другие параметры | Восстановите исходное тело. Не меняйте maxPrice при повторе. |
| Окончательный отказ | Устраните причину. Только новая намеренная покупка получает новый ключ. |
Пример сохранённой операции
purchase-operation.json · example
{
"idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
"body": { "service": "tg", "country": 0, "maxPrice": 50 },
"state": "created",
"orderId": null
}Обратите внимание
state и orderId в этом примере — поля вашей БД, не параметры API. Публичный API не предоставляет поиск операции по Idempotency-Key или гарантированный срок хранения ключа.
Восстановление после неопределённого результата
Сопоставление истории только по цене и времени неоднозначно при параллельных покупках. Надёжнее повторить исходную операцию с сохранённым ключом. Если результат остаётся неизвестным, сохраните контекст и обратитесь в поддержку; не запускайте бесконечные повторы.
Не нашли ответ на свой вопрос?Помощь с интеграцией