Лимиты запросов и ошибки
Ограничения и что означает каждый код состояния.
429 может прийти с нескольких уровней:
- Наш лимит на бесплатные модели: 1 запрос в минуту, на каждую бесплатную модель, на каждого пользователя.
- Лимиты на стороне провайдера: провайдер за бесплатной моделью упёрся в собственный предел.
- Суточные бюджеты токенов в некоторых бесплатных пулах, сбрасываются в полночь UTC.
- Ограничения токенов в минуту, срабатывают на очень больших промптах.
- Ограничение параллельных запросов на пользователя.
У платных моделей нет лимитов запросов, накладываемых UnoRouter.
Когда срабатывает лимит в 1 запрос в минуту, вы получаете стандартные заголовки ограничения запросов:
HTTP/1.1 429 Too Many Requests
Retry-After: 38
X-RateLimit-Limit: 1
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1783198478Retry-After содержит число секунд, оставшихся в вашем окне, а не всегда 60. В сообщении называется платная модель, у которой лимита нет.
Некоторые платные модели доступны бесплатно с ограничением размера запроса. На слишком больших промптах возвращается 413: Request body too large for gpt-4.1 model. Max size: 8000 tokens.
Ограничение действует только на бесплатном маршруте. Платная модель принимает промпты любой длины.
Ошибки возвращаются в формате ошибок OpenAI в JSON. Поле code является стабильным идентификатором. К каждому сообщению добавляется id запроса:
{
"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 запроса в обращениях в поддержку. Он позволяет найти ваш запрос в логах.
Если вы еще настраиваете ключ или базовый URL, начните с Быстрый старт
Коды состояния, с которыми вы реально столкнётесь:
| Код | Значение | Что делать |
|---|---|---|
400 | Некорректный запрос: неверный параметр или промпт, заблокированный модерацией. | Исправьте запрос. Повтор без изменений снова не пройдёт. |
401 | Отсутствующий, неверный, просроченный или отключённый ключ. | Проверьте заголовок Authorization и страницу Tokens. |
402 | Собственный лимит расходов этого ключа исчерпан. | Повысьте лимит ключа или создайте новый ключ. |
403 | Пустой баланс, модель не разрешена для этого ключа или IP не в списке разрешённых. | Пополните баланс или проверьте ограничения ключа по моделям и IP. |
413 | Запрос превышает ограничение на размер для бесплатного пробного доступа к модели. | Сократите промпт или переключитесь на платную модель. |
429 | Сработал лимит запросов (см. виды ниже). | Подождите количество секунд из Retry-After, затем повторите или смените модель. |
500 | Что-то отказало на нашей стороне или у upstream-провайдера. | Повторите попытку через некоторое время. О повторяющихся 500 сообщайте нам. |
503 | Все провайдеры заняты или имя модели не существует. | Читайте сообщение: занятость проходит за минуты, опечатка нет. |
Две очень разные ситуации делят статус 503. Первая это временная перегрузка:
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 означает, что имя не разрешается, и повтор здесь никогда не поможет. Проверьте опечатки или каталог.
Считайте get_channel_failed повторяемой ошибкой, а model_not_found жёсткой.
Модель, исчезнувшая под нагрузкой, возвращается сама; чтобы узнать об этом сразу, следите за ней в Уведомления
Если ключ закрепляет группы провайдеров, есть третий вариант 503, когда упали только ваши закреплённые группы, смотрите Закрепление групп
Соблюдайте Retry-After при 429. При 503 get_channel_failed повторяйте попытку через небольшую паузу или смените модель. Ошибки класса 400 повторять не нужно.
Неудачные и отклонённые запросы никогда не тарифицируются; как работают предудержание и возврат, описано в Аккаунт и биллинг