API Reference

Ліміти запитів

Ліміти публічного API AOA за ендпоінтами, заголовки X-RateLimit-* і як коректно обробляти 429.

Ліміти рахуються ковзним вікном. Читання щедре, запис — стриманіший: резервування й оплата зачіпають реальні місця та гроші.

Ліміти за ендпоінтами

Запит	Ліміт	Рахується за
Читання закладів і подій без ключа	60 запитів за хвилину	IP-адресою
Читання закладів і подій з ключем	600 запитів за хвилину	ключем
POST`/reservations`	60 запитів за хвилину	ключем
POST`/table-reservations`	60 запитів за хвилину	ключем
POST`/checkout`	20 запитів за 10 хвилин	ключем
GET`/orders/{paymentId}`	600 запитів за хвилину	ключем

Ключ піднімає ліміт удесятеро

Навіть там, де ключ не обовʼязковий, надсилайте його: 60 запитів на хвилину з одного IP вичерпуються швидко, якщо ваш сервер обслуговує кількох користувачів одночасно.

Ліміт статусу замовлення навмисно високий — це той самий рівень, що й для читання подій. Опитувати статус раз на 5–10 секунд можна спокійно.

Заголовки

Кожна відповідь несе поточний стан ліміту:

HTTP

HTTP/1.1 200 OK
RateLimit-Policy: "default";q=600;w=60
RateLimit: "default";r=597;t=60
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 597

Заголовок	Значення
`RateLimit-Policy`	Квота: q запитів на вікно w секунд (чернетка IETF RateLimit)
`RateLimit`	Стан квоти: r лишилось, t секунд до поповнення. Вікно ковзне, тож t означає верхню межу
`X-RateLimit-Limit`	Скільки запитів дозволено у вікні
`X-RateLimit-Remaining`	Скільки лишилось до кінця вікна
`Retry-After`	Через скільки секунд повторювати. Приходить лише разом із 429

Коли ліміт вичерпано

Запит повертає 429 з кодом rate_limited:

HTTP

HTTP/1.1 429 Too Many Requests
RateLimit-Policy: "default";q=600;w=60
RateLimit: "default";r=0;t=42
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
Retry-After: 42

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests"
  }
}

Чекайте стільки, скільки каже Retry-After, і повторюйте. Ретраї без паузи лише подовжують вікно блокування.

JavaScript

async function callApi(url, options, attempt = 0) {
  const response = await fetch(url, options);

  if (response.status === 429 && attempt < 3) {
    const retryAfter = Number(response.headers.get('Retry-After') ?? 1);
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
    return callApi(url, options, attempt + 1);
  }

  return response;
}

Як не впиратись у ліміт

Кешуйте список подій у себе на кілька хвилин. Афіша не змінюється щосекунди, а от залишок місць — так.
Для актуальних залишків беріть /availability: одна відповідь містить усі типи квитків події, тож не треба опитувати кожен окремо.
Створюйте платіж лише тоді, коли покупець справді натиснув «Оплатити». Ліміт у 20 за 10 хвилин розрахований саме на реальні спроби оплати.
Опитуючи статус замовлення, зупиняйтесь на термінальному статусі — SUCCESS, FAILED, EXPIRED, REFUNDED.

Якщо вашій інтеграції потрібні вищі ліміти — напишіть нам, розберемось окремо.