Руководства
Коды ошибок
Расшифровка ошибок OneProvider: что значит каждый код статуса, точный текст, лимиты времени, ошибки внутри стрима и когда запрос безопасно повторять.
Что означает каждый код, какое сообщение вы увидите и что делать дальше.
Все модели, характеристики и цены Индекс документации для AI-агентов:https://oneprovider.dev/docs/llms.txt Форма ошибки
Все ошибки приходят в JSON одной формы на всех эндпоинтах (/v1/messages, /v1/chat/completions, /v1/responses, /v1/models). У ошибки баланса есть ещё поле code:
{
"type": "error",
"error": {
"type": "insufficient_balance",
"code": "insufficient_quota",
"message": "Insufficient balance on this API key. Top up: dashboard.oneprovider.dev"
}
}OpenAI SDK читают error.message из этого тела как обычно, поэтому текст ошибки одинаков в любом клиенте.
Коды статуса
| Код | error.type | Сообщение и смысл | Что делать |
|---|---|---|---|
| 400 | invalid_request_error | Запрос составлен неверно: битый JSON, нет обязательного поля или недопустимое значение. Текст сообщения называет проблему. | Исправьте то, что указано в сообщении, и отправьте снова. Повтор без изменений вернёт ту же ошибку. |
| 400 | invalid_request_error | prompt is too long: N tokens > M maximum Вход больше контекстного окна этой модели. N и M зависят от модели. | Сократите историю или вложения либо выберите модель с большим контекстом. Claude Code в этом случае сам сжимает диалог. |
| 400 | invalid_request_error | Model X is not available on this API key Тариф ключа не включает эту модель. | Выберите модель из GET /v1/models или со страницы цен. |
| 401 | authentication_error | Invalid API key API key is required Ключ не передан, введён с ошибкой или отправлен не в том заголовке. | Передайте ключ sk-… без кавычек и пробелов в x-api-key или Authorization: Bearer. |
| 401 | authentication_error | API key is disabled Ключ отключён или аккаунт неактивен. | Проверьте ключ в кабинете (раздел «Ключи») или напишите в @Oneproviderhelpbot. |
| 403 | permission_error | API key expired Срок действия ключа истёк. | Продлите ключ или выпустите новый в кабинете (раздел «Ключи»). |
| 404 | not_found_error | The requested API endpoint does not exist Обычно это неверный base URL, например /v1/v1 в пути. | Claude Code и Anthropic SDK: https://api.oneprovider.dev. OpenAI SDK и OpenAI-совместимые клиенты: https://api.oneprovider.dev/v1. |
| 413 | invalid_request_error | request body exceeds size limit Тело запроса больше 32 МБ. | Уменьшите картинки и файлы, отправляйте их меньше или разбейте задачу на несколько запросов. |
| 429 | insufficient_balance | Insufficient balance on this API key. Top up: dashboard.oneprovider.dev Баланс кабинета или лимит трат ключа исчерпан. В ответе есть error.code insufficient_quota и заголовок x-should-retry: false. | Не повторяйте запрос. Пополните кабинет (бот или app.oneprovider.dev) либо поднимите лимит ключа и отправьте запрос снова. |
| 429 | rate_limit_error | Rate limit exceeded; retry later Слишком много запросов за короткое время. Может прийти заголовок Retry-After. | Подождите Retry-After секунд, если он есть, иначе повторяйте с растущей паузой. Если повторяется, уменьшите число параллельных запросов. |
| 500, 502 | server_error | Service temporarily unavailable; retry later Временный сбой на нашей стороне. | Повторите запрос с растущей паузой. |
| 503 | server_error | Temporary provider issue on our side, retry in a minute Service temporarily unavailable; retry later Временная ситуация. С ключом и запросом всё в порядке. | Повторите с растущей паузой, обычно проходит за минуту. |
| 504 | server_error | Service timed out; retry later Запрос не уложился в лимит времени (см. ниже). | Повторите. Для длинных ответов включите stream: true. |
Лимиты времени
- Запрос без стриминга должен начать отвечать в течение 6 минут.
- Любой запрос, со стримингом тоже, ограничен 10 минутами.
- Для длинных генераций включайте
stream: true: стрим начинает отвечать сразу. Если один ответ не укладывается в 10 минут, разбейте задачу на части.
Ошибки внутри стрима
Когда стрим уже начался, код ответа уже 200, поэтому ошибка приходит событием. Messages API присылает кадр event: error с тем же телом ошибки, Responses API присылает событие response.failed, причина лежит в response.error.
event: error
data: {"type":"error","error":{"type":"server_error","message":"Service temporarily unavailable; retry later"}}Обрабатывайте его как соответствующий код статуса. Полученная часть ответа неполная: если ошибку можно повторять, отправьте запрос целиком заново.
Когда повторять
- Не повторяйте, сначала исправьте: 400, 401, 403, 404, 413 и 429 с
insufficient_balance. Тот же запрос упадёт так же, пока вы не поменяете запрос, ключ или баланс. - Повторяйте с растущей паузой: 429
rate_limit_error, 500, 502, 503, 504. Например 1 с, 2 с, 4 с и дальше до минуты, с небольшим случайным разбросом. Если естьRetry-After, ждите не меньше. - Учитывайте
x-should-retry: false. Официальные Anthropic и OpenAI SDK уже так делают и не повторяют ошибку баланса. - Остаток баланса показывает
GET /v1/dashboard/balance, см. Использование и биллинг .
Как реагируют популярные клиенты
- Claude Code. Показывает сообщение в сессии. После 401 Claude Code 2.1.231 и новее удаляет сохранённый ключ: проверьте ключ и base URL (https://api.oneprovider.dev, без /v1), затем задайте ключ заново. На ошибке баланса сразу останавливается: пополните кабинет и продолжайте. На «prompt is too long» сам сжимает диалог. Временные 429 и 5xx повторяет автоматически.
- Cursor. Показывает текст ошибки в чате. Проверьте API-ключ и base URL https://api.oneprovider.dev/v1 в настройках моделей, при ошибке баланса пополните кабинет, затем отправьте сообщение снова.
- Codex. Ошибку баланса показывает как «Quota exceeded» и останавливается: пополните кабинет и запустите команду снова. Временные ошибки сначала повторяет сам.
- Cline. Показывает ошибку в задаче с кнопкой Retry. Сначала исправьте ключ, base URL или баланс, затем нажмите Retry.
- Continue. Показывает текст ошибки в панели чата. Исправьте причину и отправьте сообщение снова.