Надёжность и идемпотентность

Идемпотентные запросы

Для каждого логического изменяющего действия создавайте отдельный X-Idempotency-Key:

site-order-100-create
site-order-100-paid
site-order-100-cancel
refund-dbd54426-processing
refund-dbd54426-succeeded

Если HTTP-ответ потерян, повторите тот же метод, URL и тело с тем же ключом. MenuLab вернёт сохранённый результат и заголовок X-Idempotent-Replayed: true. Нельзя использовать прежний ключ с другим телом.

Что хранить у себя

external_id
  → MenuLab order_id
  → external payment_id
  → refund_request_id
  → external_refund_id

Эта связь позволяет восстановить процесс без повторного платежа или возврата.

Повторы запросов

• 400, 401, 403, 404, 409, 422: автоматический повтор без изменения причины обычно бесполезен.
• 429: ждать время из Retry-After или meta.reset_at.
• 500/503 и сетевой сбой: повторить с тем же idempotency key и неизменным телом.
• неизвестный результат эквайера: проверить существующую операцию у эквайера, не создавать новую.

Используйте exponential backoff с небольшим jitter и ограничением числа попыток. После исчерпания попыток сохраните задачу для ручного разбора; не запускайте бесконечный частый цикл.

Polling как страховка

Webhook — основной канал. Периодическая сверка допустима для незавершённых заказов и возвратов, но не опрашивайте все заказы ресторана каждую секунду.

Для заказа используйте компактный /orders/status; для возврата — GET /api/v1/refunds/{refund_request_id}. После терминального статуса прекратите polling.

Защита от двойного возврата

Дедуплицируйте webhook по event_id, бизнес-операцию — по refund_request_id, а вызов провайдера — его ключом идемпотентности. succeeded подтверждайте только после однозначного успеха у провайдера.