Повтори та Backoff

Движок повторів MirApi Gateway автоматично повторно надсилає невдалі запити з exponential backoff та jitter, захищаючи ваші інтеграції від тимчасових збоїв upstream — тайм-аутів, помилок 5xx та обривів з’єднання.

Як це працює

При збої upstream (помилка з’єднання або відповідь 5xx) шлюз чекає і повторює автоматично. Затримка розраховується за формулою:

delay = base_delay × 2^attempt + random_jitter (до 50% від затримки)

Максимальна затримка обмежена 10 секундами на спробу. Якщо одна з повторних спроб успішна, шлюз повертає клієнту відповідь разом із діагностичним заголовком X-Rescued: retry. Приклад з X-Retry-Delay: 200ms та X-Retry-Count: 4:

Перша спроба: → збій (503)
Повтор 1: чекаємо ~200ms + jitter → повтор
Повтор 2: чекаємо ~400ms + jitter → повтор
Повтор 3: чекаємо ~800ms + jitter → повтор
Повтор 4: чекаємо ~1600ms + jitter → повтор або здатися

Jitter розподіляє навантаження повторів між кількома клієнтами, щоб вони не бомбардували запитами upstream одночасно.

Заголовки

Заголовок	За замовч.	Опис
X-Retry-Count	0	Кількість повторних спроб (0 = вимкнено)
X-Retry-Delay	100ms	Базова затримка для exponential backoff. Приймає Go durations: 100ms, 500ms, 1s
X-Proxy-Timeout	30s	Тайм-аут на спробу. Приймає Go durations: 1s, 5s, 30s. Максимальне значення: 30s.

Варіанти використання

1. Базові повтори при тимчасових збоях

curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.stripe.com/v1/charges" \
  -H "X-Identity-Key: Bearer sk_live_..." \
  -H "X-Retry-Count: 3" \
  -H "X-Retry-Delay: 500ms" \
  -H "X-Proxy-Timeout: 5s" \
  -d '{"amount": 2000, "currency": "usd", "source": "tok_visa"}'

2. Повтори з ключем idempotency (Платежі)

Для платіжних ендпоінтів завжди поєднуйте повтори з X-Proxy-Idempotency-Key:

curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.stripe.com/v1/charges" \
  -H "X-Identity-Key: Bearer sk_live_..." \
  -H "X-Retry-Count: 3" \
  -H "X-Retry-Delay: 1s" \
  -H "X-Proxy-Timeout: 10s" \
  -H "X-Proxy-Idempotency-Key: order_789_charge_attempt_1" \
  -d '{"amount": 9900, "currency": "usd", "source": "tok_visa"}'

Обережно

Завжди використовуйте X-Proxy-Idempotency-Key з повторами для платіжних ендпоінтів, щоб запобігти дублікатним списанням.

3. Повтори + Smart Cache fallback

Якщо всі повтори провалились — повернути кешовану відповідь:

curl https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.exchangerate.host/latest" \
  -H "X-Retry-Count: 3" \
  -H "X-Retry-Delay: 200ms" \
  -H "X-Smart-Cache: 300s"
# Якщо всі 3 повтори провалились → кеш → X-Rescued: cache

4. Повтори + Failover URL

Після провалу всіх повторів primary — спробувати резервний ендпоінт:

curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://primary-bank.com/api/charge" \
  -H "X-Failover-URL: https://backup-bank.com/api/charge" \
  -H "X-Retry-Count: 2" \
  -H "X-Retry-Delay: 500ms" \
  -H "X-Proxy-Timeout: 8s"
# primary провалився × 2 → backup → X-Rescued: failover

5. Async повтори (тривалі завдання)

Для операцій де upstream може не відповідати хвилинами або годинами:

curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.stripe.com/v1/charges" \
  -H "X-Webhook-Callback: https://your-app.com/webhook" \
  -H "X-Proxy-Idempotency-Key: order_789_attempt_1" \
  -H "X-Retry-Count: 5" \
  -H "X-Retry-Delay: 2s"
# Повертає 202 негайно
# Воркер повторює: 2s, 4s, 8s, 10s (обмежено), 10s+jitter
# POST з результатом на callback коли Stripe відповів

Часи backoff

Спроба	X-Retry-Delay: 100ms	X-Retry-Delay: 500ms	X-Retry-Delay: 1s
1	~100ms + jitter	~500ms + jitter	~1s + jitter
2	~200ms + jitter	~1000ms + jitter	~2s + jitter
3	~400ms + jitter	~2000ms + jitter	~4s + jitter
4	~800ms + jitter	~4000ms + jitter	~8s + jitter
5	~1600ms + jitter	~8000ms + jitter	~10s (обмежено)

Всі затримки обмежені максимумом 10 секунд.