Лимиты и квоты

Три независимых ограничения — частота запросов и concurrency на ключ, а также баланс AI-кредитов.

Основы

Шлюз применяет три независимых ограничения: request rate limit на ключ, concurrency limit на ключ и баланс AI-кредитов аккаунта. Они предотвращают разные типы перегрузки и используют разные error details и правила восстановления.

Краткая таблица

Ограничение	Что считается	Область	Ошибка 429	`Retry-After`	Освобождение или сброс
Request rate limit	запросы в настроенном окне	один ключ	type `rate_limit_exceeded`, code null	`60` секунд	По мере продвижения окна
Concurrency limit	выполняющиеся сейчас запросы	один ключ	type `insufficient_quota`, code `concurrency_limit`	`1` секунда	После завершения выполняющегося запроса или stream
Баланс AI-кредитов	взвешенные AI-кредиты (4 корзины)	аккаунт, все ключи	type `insufficient_quota`, code null	`60` секунд	После пополнения баланса пакетом кредитов

Ещё один вариант 429, upstream_rate_limited, не относится к этим ограничениям: upstream-провайдер ограничивает сам шлюз. Различия описаны в разделе «Ошибки».

Request rate limit на ключ

Для каждого API key задаётся свой лимит запросов. При превышении:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "error": { "message": "Rate limit exceeded", "type": "rate_limit_exceeded", "code": null }
}

Что делать

Повторяйте запросы с экспоненциальной задержкой и jitter; пример есть в разделе «Ошибки».
Если лимит достигается регулярно, попросите контактное лицо шлюза повысить его либо разделите нагрузку между ключами с разным назначением.
Если один ключ используется многими процессами, выдайте каждому процессу собственный ключ или соберите запросы через единый broker перед шлюзом.

Concurrency limit на ключ

У каждого API key есть предел одновременно выполняющихся запросов. Потоковый запрос занимает слот до завершения stream. При достижении предела OpenAI-compatible generation endpoints возвращают HTTP 429 с type: "insufficient_quota", code: "concurrency_limit" и Retry-After: 1.

Поставьте работу в локальную очередь или уменьшите параллелизм перед повтором. Ограничение освобождается по мере завершения активных запросов и не расходует баланс AI-кредитов.

Баланс AI-кредитов

У аккаунта есть баланс AI-кредитов. Каждый успешный ответ списывает взвешенные AI-кредиты, рассчитанные из четырёх корзин: обычный input, cache read, cache write и output. Стоимость зависит от модели, типа токенов и кэширования. После исчерпания баланса:

{
  "error": { "message": "AI credit quota exhausted", "type": "insufficient_quota", "code": null }
}

Что делать

Купите пакет AI-кредитов, чтобы пополнить баланс: слепые повторы не помогут. Баланс сохраняется между днями, ключами и процессами. Текущий runtime всё равно возвращает Retry-After: 60; считайте его минимальной задержкой, а не обещанием автоматического восстановления баланса.

Текущий расход можно получить аутентифицированным запросом GET /v1/quota: ответ содержит used, quota, remaining и статус баланса аккаунта, связанного с ключом.

Зачем нужны три ограничения

Request rate limit защищает от коротких всплесков одного процесса, например зацикленного скрипта. Concurrency limit ограничивает одновременно выполняемую upstream-работу и долгоживущие streams. Баланс AI-кредитов ограничивает долгосрочный рост стоимости, когда пользователь месяцами отправляет небольшие запросы и постепенно исчерпывает выделенный бюджет.

Все три ограничения независимы:

Один очень большой запрос может исчерпать баланс AI-кредитов, не достигнув request rate limit или concurrency limit, потому что это всего один запрос.
Несколько медленных streams могут достигнуть concurrency limit, оставаясь в пределах request-rate окна.
Быстрые короткие запросы могут достигнуть request rate limit при низкой concurrency.

Что не учитывается в этих ограничениях ключа и аккаунта

Общедоступный поиск моделей (/v1/models и /v1/catalog*). Для этих endpoints действуют собственные IP-лимиты 60 запросов в минуту, но обращения не учитываются в ограничениях ключа или баланса аккаунта.
Endpoint /health. Он всегда отвечает без аутентификации и без лимита.

Заголовки

Текущий OpenAI-compatible runtime передаёт Retry-After: 60 для request rate limit на ключ, Retry-After: 1 для concurrency limit на ключ и Retry-After: 60 при исчерпании баланса AI-кредитов. Выдержите указанную задержку перед повтором. Для баланса AI-кредитов отложенный запрос всё равно может завершиться ошибкой, пока баланс не пополнен.