Лимиты и доступность

Лимит частоты запросов

API ограничивает число запросов по ключу или сессии, а запросы без ключа и сессии — по IP-адресу клиента:

Уровень	Значение	Что получает клиент при превышении
Приложение API, запросы с API-ключом или сессией кабинета	600 запросов в минуту на каждый ключ или сессию; окно в одну минуту, общий счётчик для всех маршрутов API	HTTP 429 в обычном JSON-формате ошибки с `error.code=rate_limited`
Приложение API, запросы без ключа и сессии	300 запросов в минуту на IP-адрес; окно в одну минуту, общий счётчик для всех маршрутов API	HTTP 429 в обычном JSON-формате ошибки с `error.code=rate_limited`
Приложение API, все ключи и сессии одного IP-адреса вместе	потолок 1800 запросов в минуту на IP-адрес	HTTP 429 в том же JSON-формате, с `Retry-After`
Публичные картинки и публичный каталог моделей	1200 запросов в минуту на IP-адрес, отдельный счётчик	HTTP 429 в обычном JSON-формате ошибки с `error.code=rate_limited`
Вход на `api.kvantora.ai`	около 30 запросов в секунду на IP-адрес, кратковременный всплеск — ещё до 90 запросов	HTTP 429 от входного сервера: HTML-страница вместо JSON, без `error.code` и без `Retry-After`
Вход в кабинет (`/api/auth/*`)	около 5 запросов в минуту на IP-адрес, запас — 10 запросов	HTTP 429 входного сервера; к вызовам API по ключу не относится

У каждого ключа и каждой сессии свой счётчик: сотрудники и ключи компании за одним IP-адресом (офис, NAT) не делят один лимит, а общий потолок по адресу защищает от подбора и перегрузки. Несколько серверов с одним ключом делят счётчик этого ключа. Лимит не зависит от баланса и дневного бюджета ключа.

Ответ 429 приложения

{
  "error": {
    "code": "rate_limited",
    "message": "Слишком много запросов. Подождите и повторите попытку: время ожидания указано в заголовке Retry-After",
    "request_id": "req-…"
  }
}

Приложение сообщает состояние окна заголовками:

Заголовок	Значение
`x-ratelimit-limit`	Сколько запросов разрешено за окно (600 с ключом или сессией, 300 без них)
`x-ratelimit-remaining`	Сколько запросов осталось в текущем окне
`x-ratelimit-reset`	Через сколько секунд окно обновится
`Retry-After`	В ответе 429: через сколько секунд повторить запрос

Если заголовок Retry-After присутствует, выдержите указанную паузу. Если его нет (ответ входного сервера — HTML без Retry-After), подождите не менее секунды, затем повторяйте с нарастающей паузой и более редким темпом. Не используйте бесконечный автоматический повтор: ограничьте число попыток и увеличивайте паузу.

Отказ по частоте происходит до обработки запроса: резерв не создаётся и деньги не списываются. Повторяйте запрос с прежними телом и Idempotency-Key: если исходный запрос всё же был принят, вы получите его сохранённый результат, а не второй платный запуск. Ограничьте пул параллельных запросов заранее, не ждите 429.

Другие причины HTTP 429

HTTP 429 бывает и у дневного бюджета ключа. Различайте причины по error.code:

`error.code`	Причина	Действие
`rate_limited`	Исчерпан лимит запросов в минуту	Подождать `Retry-After` и повторить тот же запрос
`api_key_daily_budget_exceeded`	Исчерпан дневной бюджет ключа	Повтор до смены дня не поможет: проверьте бюджет и резервы или задайте другой ключ

Для api_key_daily_budget_exceeded в error.details приходят limit, spent, reserved, remaining (целые числа в микрорублях) и reset_at — момент, когда бюджет обновится.

Недоступность и MCP

Временная перегрузка возвращается как HTTP 503 service_unavailable с заголовком Retry-After, см. ошибки.

Для MCP одновременно выполняются до двух инструментов на организацию и до четырёх на процесс. Превышение возвращает isError=true и mcp_busy. Эти слоты не используются обычными API-запросами. Отключение MCP не отключает API.

Ограничения размера

Тело JSON-запроса API до 10 МиБ, MCP body до 64 КиБ, MCP result до 512 КиБ, файл до 50 МиБ. Дополнительные ограничения строк и массивов описаны в матрице совместимости.

Отказ доступности до отправки не равен неизвестному результату после отправки. Для неизвестного результата сохраняйте ID и резерв, см. ошибки.