Неудачный запрос возвращает HTTP-код и тело с описанием причины. Причины бывают двух видов: проверки на стороне ProxyAPI — ключ, баланс, доступ к модели — и ошибки, которые вернул конечный сервис.
Проверки ProxyAPI отвечают полем detail:
{ "detail": "Insufficient balance to run this request." }
Ошибка конечного сервиса приводится к формату того эндпоинта, на который пришёл запрос. Для эндпоинтов в формате OpenAI это выглядит так:
{ "error": { "message": "This model's maximum context length is 128000 tokens.", "type": "invalid_request_error", "param": null, "code": null } }
Для /v1/messages — в формате Anthropic ({"type": "error", "error": {…}}), для /v1beta — в формате Google ({"error": {"code", "message", "status"}}). Обработка ошибок в коде, написанном под конкретный формат, менять не нужно.
| Код | Причина | Что делать |
|---|---|---|
| 400 | Запрос не соответствует формату: неверный JSON, неизвестное поле, недопустимое значение | Проверить тело запроса |
| 401 | Ключ не распознан, не определён IP-адрес запроса или аккаунт заблокирован | Проверить ключ и базовый адрес |
| 402 | Недостаточно средств на балансе либо исчерпан бюджет ключа | Пополнить баланс или поднять бюджет ключа |
| 403 | Модель не входит в список разрешённых для ключа, IP-адрес не в белом списке, эндпоинт ключу не разрешён | Проверить настройки ключа |
| 404 | Модель или файл с таким идентификатором не найдены | Сверить идентификатор с каталогом |
| 429 | Превышен лимит частоты запросов | Повторить запрос позже |
| 502 | Конечный сервис недоступен или ни один из них не ответил | Повторить запрос |
| 504 | Истекло время ожидания ответа | Повторить запрос |
Точная причина всегда в тексте ошибки: например, у 402 это Insufficient balance to run this request., API Key budget exceeded. или Monthly budget exceeded. — три разные ситуации с одним кодом.
Отдельный случай — 402 при непустом балансе. Перед отправкой запроса его стоимость считается предварительно, с запасом на самый длинный возможный ответ, и средств должно хватать именно на эту оценку. Как она устроена и как её уменьшить — в статье Стоимость запроса.
Часть ошибок формирует не ProxyAPI, а сам сервис, которому ушёл запрос: слишком длинный контекст, недопустимое значение параметра, отказ по правилам безопасности. Такие ответы передаются с исходным кодом и исходным текстом, поэтому искать их описание нужно в документации соответствующего API.
- API-ключи — ограничения ключа, из-за которых приходят 401, 402 и 403.
- Лимиты частоты запросов — откуда берётся 429.
- Стоимость запроса — предварительный расчёт, из-за которого приходит 402.
Частые вопросы
Как понять, кто вернул ошибку — ProxyAPI или сама модель?
По телу ответа. Проверки ProxyAPI отвечают полем detail. Ошибка конечного сервиса приходит в формате эндпоинта — например, объектом error для эндпоинтов в формате OpenAI.
Почему приходит 402, если на балансе есть деньги?
Причины две. Либо исчерпан бюджет ключа или месячный бюджет — это отдельные ограничения, не связанные с остатком. Либо средств не хватает на предварительную оценку стоимости запроса, которая делается с запасом на самый длинный ответ. Точную причину показывает текст ошибки.
Что делать при ошибках 502 и 504?
Повторить запрос. 504 означает, что ответ не пришёл за отведённое время, 502 — что конечный сервис недоступен. Обе ошибки обычно временные.
Последняя редакция: 2 сентября 2026 г.