Ограничения частоты

API для разработчиков ограничивается по частоте по организации, в минуту, а бюджет задаётся вашим тарифом. Каждый аутентифицированный по key ответ сообщает, где именно вы находитесь, чтобы можно было регулировать трафик ещё до достижения лимита.

Заголовки ограничения частоты

Каждый аутентифицированный по key ответ несёт три заголовка:

Заголовок	Значение
`RateLimit-Limit`	Квота запросов вашей организации для текущего окна.
`RateLimit-Remaining`	Сколько запросов осталось в текущем окне.
`RateLimit-Reset`	Сколько секунд до сброса текущего окна.

Окно — это скользящее окно в 60 секунд; бюджет тарифа выражен в минуту. Читайте RateLimit-Remaining и снижайте темп по мере его приближения к нулю.


HTTP/1.1 200 OK
RateLimit-Limit: 120
RateLimit-Remaining: 117
RateLimit-Reset: 41
Content-Type: application/json

Когда вы превышаете лимит

Запрос сверх бюджета возвращает 429 со стандартным конвертом ошибки и заголовком Retry-After, сообщающим, сколько секунд подождать:


HTTP/1.1 429 Too Many Requests
Retry-After: 41
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 41
Content-Type: application/json


{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "You have exceeded your plan's request allowance."
  }
}

Обработка 429

Соблюдайте Retry-After — подождите указанное число секунд перед повтором.
Применяйте экспоненциальную выдержку, если продолжаете получать 429.
Используйте RateLimit-Remaining проактивно, чтобы ограничивать всплески до того, как они будут отклонены.

Отказ в открытое состояние

Ограничитель частоты спроектирован так, чтобы отказывать в открытое состояние: если сам ограничитель недоступен, запросы пропускаются, а не блокируются. Вы никогда не должны видеть ложных 429, вызванных простоем ограничителя — но и не следует полагаться на ограничитель для обеспечения корректности в вашем собственном клиенте. Регулируйте трафик с помощью заголовков RateLimit-*.

Лимит запросов к agent

Запуск agent (POST /agents/{id}/query) дополнительно измеряется относительно лимита запросов к agent вашего тарифа на стороне сервера. Его превышение возвращает 429 на блокирующем пути или один событие error на потоковом пути. Подробности смотрите на странице Запрос к Agent.