Ліміти частоти та квоти

Два види лімітів підтримують швидкість API для всіх:

Ліміт частоти ключа: скільки запитів на секунду він може надсилати, зі сплеском (burst) для коротких піків.
Квоти організації: скільки запитів усі її ключі разом можуть надіслати за хвилину, за день і за місяць.

Обидва види лімітів залежать від тарифу організації. Кожна відповідь повідомляє, де ви перебуваєте відносно лімітів, тож коректному клієнтові ніколи не доводиться вгадувати.

Ліміт частоти ключа

Кожен ключ отримує сталу частоту й сплеск. Сплеск дозволяє надіслати стільки запитів одразу; після цього запити дозволено зі сталою частотою.

Клас	Частота	Сплеск
`basic`	5 запитів на секунду	25
`standard`	20 запитів на секунду	100
`high`	50 запитів на секунду	250

Клас визначає тариф організації. GET /v1/me показує клас, частоту й сплеск ключа, який її викликає (rate_limit). Ліміт діє для ключа загалом, скільки б серверів API не обслуговувало ваші запити.

Потокові операції, POST /v1/chat (з "stream": true чи без нього) і GET /v1/jobs/stream, перебувають поза лімітом частоти ключа: вони його не витрачають, а їхні заголовки RateLimit не мають елемента "key". Проте вони зараховуються до квот організації, кожна один раз, коли запит починається. Запитання мають власні ліміти, описані нижче.

Квоти організації

Тариф може задавати квоти запитів для організації: за хвилину, за день і за місяць. Вікна — календарні періоди в UTC: хвилина починається з нульової секунди (:00), день — о 00:00 UTC, місяць — першого числа о 00:00 UTC. Зараховується кожен запит із ключем або токеном OAuth організації, на будь-яку адресу. Потоковий запит зараховується один раз, коли починається, хоч би скільки він тривав; коли квоту вичерпано, його відхиляють із 429, як і будь-який інший запит. Запит, відхилений із 429, не зараховується.

Заголовки

Кожна відповідь на запит із ключем містить ліміти, що до нього застосовуються:

RateLimit-Policy: "key";q=100;w=5, "minute";q=1200;w=60, "day";q=200000;w=86400
RateLimit: "key";r=87;t=1, "minute";r=1150;t=23, "day";r=180311;t=40213
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1

RateLimit-Policy і RateLimit відповідають чернетці IETF RateLimit header fields for HTTP. Кожен елемент — це один ліміт:

Елемент	Значення
`"key"`	Ліміт частоти ключа. `q` — сплеск, `w` — кількість секунд, за які використаний сплеск відновлюється.
`"minute"`, `"day"`, `"month"`	Квота організації, якщо тариф її має. `q` — квота, `w` — вікно в секундах.
`r` (у `RateLimit`)	Скільки запитів лишилося в межах цього ліміту.
`t` (у `RateLimit`)	Кількість секунд до відновлення цього ліміту.

X-RateLimit-Limit, X-RateLimit-Remaining і X-RateLimit-Reset повідомляють про найсуворіший із цих лімітів у простішій формі — для клієнтів, написаних ще до появи RateLimit. X-RateLimit-Reset вказано в секундах.

Коли ліміт досягнуто

API відповідає 429 Too Many Requests із заголовком Retry-After у секундах:

Код	Значення
`api.rate_limited`	Ключ надсилав запити швидше, ніж дозволяє його частота. `Retry-After` зазвичай становить секунду-дві.
`api.quota_exceeded`	Квоту організації вичерпано. `details` повідомляє, яку саме і коли вона відновиться.

{
  "detail": "the organization has used its API request quota for this period",
  "error": {
    "code": "api.quota_exceeded",
    "message": "the organization has used its API request quota for this period",
    "details": {"quota": "day", "limit": 200000, "reset_at": "2026-10-25T00:00:00Z", "retry_after": 40213},
    "request_id": "01JB7…"
  }
}

Зачекайте Retry-After і повторіть запит. Повторюйте POST і PATCH із тим самим Idempotency-Key. Допоміжні функції повторів на сторінці Помилки роблять і те, і те.

Інші ліміти тарифу також відповідають 429 з Retry-After, наприклад кількість запитань на день (limits.questions) або кількість відповідей, що готуються одночасно (limits.concurrent_answers). Обробляйте їх так само.

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

Читайте RateLimit і сповільнюйтеся, коли r стає малим, а не чекайте на 429.
Розподіляйте масову роботу в часі й використовуйте пакетні операції там, де вони є: один пакет зі 100 документів — це один запит.
Не опитуйте зміни в щільному циклі. Підпишіться на вебхуки або читайте стрічку подій раз на кілька секунд.
Запускайте паралельні обробники зі спільним обмежувачем частоти. Кілька процесів з одним ключем мають один спільний ліміт частоти.
Якщо вашій інтеграції потрібно більше, запитайте про вищий клас у свого контакту в Sursa.