ДокументацияСправочник APIОшибки

Ошибки

Три формата ошибок, соответствие категорий HTTP-статусам и типичные ошибки.

Шлюз предоставляет три формата API, и тело ошибки повторяет формат вызванного API — по пути запроса: /v1/messages* — формат Anthropic, /v1beta/* — формат Google, остальное — формат OpenAI. Благодаря этому разбор ошибок в каждом SDK работает как ожидается.

Три формата ошибок

OpenAI

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}

Anthropic

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

Google

{
  "error": {
    "code": 401,
    "message": "Invalid API key",
    "status": "UNAUTHENTICATED"
  }
}

Категории и коды статусов

Категория	HTTP	OpenAI `type`	Anthropic `type`	Google `status`
Аутентификация	401	`invalid_request_error`	`authentication_error`	`UNAUTHENTICATED`
Права доступа	403	`invalid_request_error`	`permission_error`	`PERMISSION_DENIED`
Не найдено	404	`invalid_request_error`	`not_found_error`	`NOT_FOUND`
Неподдерживаемый эндпоинт	404	`invalid_request_error`	`not_found_error`	`INVALID_ARGUMENT`
Некорректный запрос	400	`invalid_request_error`	`invalid_request_error`	`INVALID_ARGUMENT`
Лимит запросов	429	`rate_limit_error`	`rate_limit_error`	`RESOURCE_EXHAUSTED`
Квота / баланс	402	`insufficient_quota`	`billing_error`	`RESOURCE_EXHAUSTED`
Слишком большое тело	413	`invalid_request_error`	`invalid_request_error`	`INVALID_ARGUMENT`
Сбой источника	502	`api_error`	`api_error`	`UNAVAILABLE`
Перегрузка	503	`server_error`	`overloaded_error`	`UNAVAILABLE`
Внутренняя ошибка	500	`api_error`	`api_error`	`INTERNAL`

Типичные ошибки

Идентификатор	HTTP	Значение и действия
`key_missing` / `key_invalid`	401	Ключ отсутствует или недействителен — проверьте заголовок авторизации.
`key_disabled` / `key_expired` / `key_ip_denied`	403	Ключ отключён, истёк или ваш IP не в списке разрешённых.
`key_quota_exhausted`	402	Исчерпан лимит расходов ключа — дождитесь сброса или увеличьте лимит.
`balance_exhausted`	402	Недостаточно средств — пополните баланс и повторите.
`rpm_exceeded` / `concurrent_exceeded`	429	Превышен лимит RPM или конкурентности — повторите с задержкой.
`model_missing`	400	В запросе отсутствует поле `model`.
`model_not_found` / `model_disabled`	404	Модель не существует или снята — сверьте id со списком Моделей.
`no_upstream_for_model`	404	Нет источника, обслуживающего эту модель, — повторите позже или обратитесь к администратору.
`moderation_blocked`	403	Заблокировано модерацией — измените запрос и повторите.
`body_too_large`	413	Тело превышает лимит эндпоинта — сожмите встроенные медиа или используйте другой эндпоинт.
`upstream_timeout` / `upstream_unreachable` / `all_upstreams_down`	502	Источник не отвечает, недоступен или все источники отключены — повторите с задержкой.
`server_busy`	503	Шлюз перегружен запросами в обработке — повторите позже.
`balance_insufficient`	402	Баланс за вычетом оценочной стоимости выполняющихся запросов не покрывает этот запрос (см. Баланс аккаунта) — пополните счёт или дождитесь завершения запросов.
`entry_unsupported`	404	Путь/метод не является эндпоинтом, который поддерживает шлюз.
`model_rejects_format` / `no_endpoint_for_format`	404	Модель не принимает протокол этого эндпоинта, либо нет апстрима с таким протоколом — используйте нативный эндпоинт модели (Responses для GPT, Messages для Claude и т. д.).
`model_not_schedulable` / `no_group_available`	404 / 403	Модель вне доступного вам диапазона, или нет видимой вам группы маршрутизации — обратитесь к администратору.
`client_not_allowed`	403	Этому клиенту не разрешена ни одна группа; для собственного или незарегистрированного клиента попросите администратора зарегистрировать его.
`account_disabled` / `account_deleted`	403	Аккаунт-владелец ключа отключён или удалён.
`privacy_filter_failed`	500	Фильтрация приватных данных завершилась ошибкой, запрос отклонён — попросите администратора проверить правила фильтра.
`video_job_missing` / `video_job_not_found` / `video_job_route_gone`	400 / 404 / 502	Опрос видео без id задания, неизвестное задание или задание, чей апстрим удалён (см. Изображения и видео).

Сообщения об ошибках локализуются под язык аккаунта (до аутентификации — Accept-Language, по умолчанию английский). В коде ориентируйтесь на HTTP-статус и поле type/status, а не на текст сообщения.

Конкретные схемы повторов и задержек — в разделе Обработка ошибок и повторы.