Ошибки

Стандартная оболочка ошибки, текущие коды шлюза и безопасные правила повторов.

Основы

Ошибочные ответы используют стандартную оболочку, поэтому клиент может проверить HTTP-статус, error.type и nullable-поле error.code. Исходные тела ошибок upstream клиенту не передаются. Таблицы ниже описывают текущее поведение публичных маршрутов /v1/*, но не обещают, что в будущем не появятся дополнительные коды.

Формат оболочки

{
  "error": {
    "message": "Upstream rate-limited",
    "type": "api_error",
    "code": "upstream_rate_limited"
  }
}

Поля:

message — безопасное для клиента описание.
type — общая категория, например invalid_request_error, authentication_error, insufficient_quota или api_error.
code — более точный идентификатор, если конкретный путь его задаёт; значение может быть null.

Основные коды клиента и шлюза

Код	HTTP	Значение	Действие
`payload_too_large`	413	Тело запроса превысило лимит маршрута	Уменьшите payload
`invalid_body`	400	JSON или схема запроса некорректны	Исправьте тело запроса
`model_not_found`	404	Слаг модели неизвестен или отключён	Проверьте слаг и состояние каталога
`model_does_not_support_images`	400	`image_url` передан модели без vision	Выберите vision-модель или удалите изображение
`multimodal_not_supported`	400	Передан неподдерживаемый тип content part, отличный от поддерживаемого текста или изображения	Удалите неподдерживаемую часть
`tool_choice_not_supported`	400	Запрошен принудительный выбор инструмента	Используйте автоматический выбор или уберите `tool_choice`
`response_format_not_supported`	400	Запрошено поле `response_format` / structured output	Уберите `response_format`; `generateObject` не поддерживается
`concurrency_limit`	429	Для ключа одновременно выполняется слишком много запросов	Повторите после указанной короткой задержки
`idempotency_conflict`	422	`Idempotency-Key` повторно использован с другим телом	Возьмите новый ключ или отправьте исходное тело
`endpoint_not_supported`	404	Запрошенный маршрут `/v1/*` не реализован	Используйте документированный endpoint
`internal_error`	500	В шлюзе возникло неожиданное исключение	Передайте оператору время, endpoint и видимые клиенту сведения

Ошибки аутентификации сейчас возвращают HTTP 401 с type: "authentication_error" и code: null. Ограничение частоты запросов ключа возвращает HTTP 429 с type: "rate_limit_exceeded" и code: null. Исчерпание баланса AI-кредитов возвращает HTTP 429 с type: "insufficient_quota" и code: null.

Коды upstream

Код	HTTP	Значение	Действие
`upstream_unavailable`	502 / 503	Нет доступного маршрута, открыт breaker или транспорт завершился до ответа	Повторите с backoff; учитывайте `Retry-After`, если он есть
`upstream_bad_request`	400	Upstream отклонил запрос	Исправьте или сократите запрос
`upstream_unauthorized`	401 / 403	Upstream отклонил учётные данные шлюза	Требуется действие оператора
`upstream_model_unavailable`	404	Настроенный внутренний id модели недоступен	Требуется действие оператора
`upstream_timeout`	408 / 504	Upstream вернул timeout-статус	Повторите с backoff
`upstream_rate_limited`	429	Upstream ограничил шлюз	Повторите с экспоненциальной задержкой и jitter
`upstream_invalid_response`	502	Непотоковый ответ upstream не прошёл разбор или проверку	Повторите; сообщите о постоянной ошибке
`upstream_error`	5xx	Upstream вернул другую ошибку или неожиданный непотоковый ответ	Повторите; сообщите о постоянной ошибке

Ошибка после начала SSE уже не может стать JSON-ответом с другим HTTP-статусом. См. «Потоковые ответы»: клиент получает finish_reason: "error" и [DONE], а во внутреннем журнале шлюза остаётся статус 502.

Безопасные повторы

Повторяйте временные upstream-ошибки upstream_unavailable, upstream_rate_limited, upstream_timeout и upstream_error, используя ограниченный экспоненциальный backoff с jitter. Не повторяйте автоматически некорректные payloads, неподдерживаемые функции, неизвестные модели, конфликты idempotency и исчерпанный баланс AI-кредитов: сначала должен измениться запрос, маршрут или состояние аккаунта.

Публичный OpenAI-compatible ответ не обещает заголовок Trace-Id. При обращении укажите timestamp, endpoint, слаг модели, HTTP-статус и полученную оболочку ошибки; оператор сможет сопоставить их с серверными request и trace-записями.