---
title: "Ліміти запитів · API Reference: документація AOA API"
description: "Ліміти публічного API AOA за ендпоінтами, заголовки X-RateLimit-* і як коректно обробляти 429."
canonical: "https://aoa.com.ua/docs/api-reference/rate-limits"
---

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

Ліміти публічного 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`.

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