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

API остаётся быстрым для всех благодаря ограничениям двух видов:

• Лимит частоты ключа: сколько запросов в секунду он может отправлять, с запасом на короткие всплески.
• Квоты организации: сколько запросов все её ключи вместе могут отправить за минуту, за день и за месяц.

И то и другое зависит от тарифа организации. Каждый ответ сообщает, сколько у вас осталось, поэтому правильно написанному клиенту никогда не приходится гадать.

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

Каждый ключ получает постоянную скорость и запас на всплеск. Запас позволяет отправить столько запросов сразу; после этого запросы разрешаются с постоянной скоростью.

Класс определяется тарифом организации. 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. Каждый элемент — один лимит:

X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset сообщают самый строгий из этих лимитов в более простом виде — для клиентов, написанных до появления RateLimit. X-RateLimit-Reset указан в секундах.

Когда лимит исчерпан

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

{
  "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 о более высоком классе.