ДокументацияСправочник 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	Шлюз перегружен запросами в обработке — повторите позже.

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

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