Руководство по платформе

Ошибки и лимиты запросов

Что означает каждый код состояния и что с ним делать.

Формат ошибки

Ошибки возвращаются как JSON в формате ошибок OpenAI. Сообщение указывает, что произошло, code это стабильный машиночитаемый идентификатор, а к каждому сообщению добавляется id запроса:

json

{
  "error": {
    "message": "Model \"gpt-5.5-typo\" is not offered here. Check the model name for typos, or switch to a model from our supported list. (request id: 20260705...)",
    "type": "new_api_error",
    "code": "model_not_found"
  }
}

Всегда указывайте id запроса, когда обращаетесь в поддержку или открываете тикет в Discord. Он позволяет нам найти ваш точный запрос в логах.

Коды состояния кратко

Коды состояния, с которыми вы реально столкнётесь:

Код	Значение	Что делать
`400`	Неверный запрос: некорректные значения параметров (например max_tokens ниже минимума модели) или промпт, заблокированный модерацией контента.	Исправьте запрос. Повтор без изменений снова провалится.
`401`	Проблема с ключом: отсутствующий, неверный, просроченный или отключённый API-ключ.	Проверьте заголовок Authorization и свой ключ на странице Токены.
`402`	Собственный лимит расходов этого ключа исчерпан.	Повысьте лимит ключа или создайте новый ключ.
`403`	Доступ запрещён: баланс аккаунта пуст, модель не разрешена для этого ключа или ваш IP отсутствует в списке разрешённых ключа.	Пополните баланс или проверьте ограничения ключа по моделям и IP.
`413`	Запрос слишком велик для лимита бесплатного пробного доступа этой модели.	Сократите промпт или переключитесь на платную модель.
`429`	Сработал лимит запросов (см. виды ниже).	Подождите количество секунд из Retry-After, затем повторите или смените модель.
`500`	Что-то отказало на нашей стороне или у upstream-провайдера.	Повторите после короткой паузы; устойчивые 500 стоит сообщить.
`503`	Все провайдеры для модели заняты, либо имя модели не существует.	Прочитайте сообщение: занятость разрешается за минуты, опечатка нет.

503: занято или неизвестная модель

Две очень разные ситуации делят статус 503. Первая это временная перегрузка:

text

HTTP/1.1 503 Service Unavailable

{
  "error": {
    "message": "All providers for model \"kimi-k2.6:free\" are busy right now (they hit their rate limit). This is not a spelling error. Please try again in a little while, or switch to another model. (request id: 20260705...)",
    "type": "new_api_error",
    "code": "get_channel_failed"
  }
}

Код get_channel_failed (все провайдеры заняты) означает, что каждый бесплатный провайдер для этой модели на мгновение упёрся в лимит запросов. Это восстанавливается само за минуты: повторите или смените модель. Код model_not_found (здесь не предлагается) означает, что само имя модели не разрешается, и повтор никогда не поможет. Проверьте опечатки или найдите текущее имя в каталоге.

Обрабатывайте 503 с get_channel_failed как повтор или резервный переход, а 503 с model_not_found как жёсткую ошибку в вашем клиенте.

Виды лимитов запросов

429 может прийти с нескольких уровней:

Наш лимит для бесплатных моделей: 1 запрос в минуту на бесплатную модель на пользователя. Лимит справедливости, чтобы общие пулы пережили часы пик.
Лимиты upstream-провайдера: провайдер за бесплатной моделью упёрся в собственный лимит ("temporarily rate-limited upstream", то есть временно ограничен по частоте на стороне upstream).
Дневные бюджеты токенов на некоторых бесплатных пулах; они сбрасываются в полночь по UTC.
Лимиты токенов в минуту, срабатывающие на очень больших промптах.
Лимит параллелизма на пользователя, когда слишком много запросов выполняется параллельно.

У платных моделей нет лимитов запросов, накладываемых UnoRouter.

Лимит бесплатных моделей подробно

Когда срабатывает наш лимит 1 в минуту, вы получаете стандартные заголовки лимита запросов, чтобы клиенты могли точно притормозить:

text

HTTP/1.1 429 Too Many Requests
Retry-After: 38
X-RateLimit-Limit: 1
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1783198478

Retry-After динамичен: это фактическое число секунд, оставшихся в вашем окне, а не фиксированные 60. Сообщение об ошибке также называет платного близнеца модели, у которого нет лимита.

Лимиты размера пробного доступа

Некоторые обычно платные модели предлагаются бесплатно с лимитом на размер запроса. Слишком крупные промпты получают 413 с сообщением вроде: Request body too large for gpt-4.1 model. Max size: 8000 tokens.

Лимит применяется только к маршруту бесплатного пробного доступа; платная модель принимает промпты полной длины.