Коды ошибок
Текущие публичные коды шлюза и случаи, в которых поле code равно null.
Справочник описывает коды, которые сейчас выдаёт публичный OpenAI-compatible интерфейс /v1/*. Он намеренно не называется исчерпывающим: новые endpoints или функции с contract-тестами могут добавлять коды. Формат оболочки и правила повторов описаны в разделе «Ошибки».
Значения, выдаваемые в error.code
| Код | HTTP | Когда возникает |
|---|---|---|
payload_too_large | 413 | Тело chat- или embeddings-запроса превышает лимит bytes |
invalid_body | 400 | Не удалось разобрать JSON или проверить схему запроса |
model_not_found | 404 | Запрошенный слаг модели неизвестен или отключён |
model_does_not_support_images | 400 | Chat-запрос содержит изображение для модели без vision |
multimodal_not_supported | 400 | Chat content part имеет неподдерживаемый тип |
tool_choice_not_supported | 400 | Запрошен принудительный выбор инструмента |
response_format_not_supported | 400 | Использовано response_format или structured-output функция SDK |
concurrency_limit | 429 | Достигнут лимит одновременно выполняемых запросов ключа |
idempotency_conflict | 422 | Один Idempotency-Key повторно использован с другим телом |
upstream_unavailable | 502 / 503 | Нет маршрута, открыт breaker или транспорт завершился до ответа |
upstream_bad_request | 400 | Upstream вернул 400 |
upstream_unauthorized | 401 / 403 | Upstream вернул 401 или 403 |
upstream_model_unavailable | 404 | Upstream вернул 404 для настроенной модели |
upstream_timeout | 408 / 504 | Upstream вернул timeout-статус |
upstream_rate_limited | 429 | Upstream вернул 429 |
upstream_invalid_response | 502 | Непотоковый ответ upstream не прошёл разбор или проверку |
upstream_error | 5xx | Возникла другая ошибка upstream или сборки ответа |
internal_error | 500 | Глобальный обработчик поймал неожиданное исключение |
endpoint_not_supported | 404 | Запрошен нереализованный endpoint /v1/* |
authentication_required | 401 | В аутентифицированном quota endpoint не определён пользователь |
Пути, где error.code равен null
Оболочка допускает code: null, и несколько текущих путей используют именно его:
- Отсутствующие или неверные учётные данные шлюза: HTTP 401,
type: "authentication_error". - Request rate limit ключа: HTTP 429,
type: "rate_limit_exceeded". - Исчерпание баланса AI-кредитов: HTTP 429,
type: "insufficient_quota".
В частности, исчерпание баланса AI-кредитов сейчас не выдаёт отдельный код. Проверяйте HTTP 429 вместе с type: "insufficient_quota" и допускайте null в поле code.
Исключение для streaming
После открытия потокового HTTP 200 ошибка посреди потока уже не может вернуть эту JSON-оболочку. Шлюз отправляет chunk с finish_reason: "error", затем [DONE], а во внутреннем журнале сохраняет статус 502. Отключение клиента записывается внутренним статусом 499 и не создаёт ответ для уже отключившегося клиента.
Публичный API не обещает заголовок ответа Trace-Id. Для расследования передайте оператору timestamp, endpoint, слаг модели, статус и полученную оболочку.