Ошибки

Формат ошибки зависит от эндпоинта: /v1/chat/completions отвечает в стиле OpenAI, /v1/messages в стиле Anthropic, /v1/responses в стиле Responses. HTTP-статус во всех трёх случаях отражает причину, и набор статусов у них общий: за ними стоят одни и те же проверки и одна и та же обработка запроса.

Формат

Chat Completions (OpenAI): объект error с полями code, message и необязательным extra.

{ "error": { "code": "model_not_found", "message": "Model 'nope/nope' is not available. Check the model name and try again.", "extra": {} } }

Ответ 401 на /v1/chat/completions и /v1/messages короче и приходит без кода: {"error":"unauthorized"}. На /v1/responses и на GET /v1/models отказ по ключу приходит обычным конвертом, с code: authentication_required, когда заголовка нет, и invalid_api_key, когда ключ не подошёл. Подробнее в Аутентификации.

Messages (Anthropic): объект с type: "error" и вложенным error с полями type, code и message. Тип ошибки по стандарту Anthropic грубый, одному типу соответствует несколько наших причин, поэтому машинный код едет рядом с ним в поле code, с тем же значением, что и в формате OpenAI. Структурированные детали, если они есть, лежат в details.

{ "type": "error", "error": { "type": "not_found_error", "code": "model_not_found", "message": "Model does not exist in the catalog" } }

Responses: объект error с полями type, code, message и необязательным param.

{ "error": { "type": "not_found_error", "code": "model_not_found", "message": "Model does not exist in the catalog" } }

Коды

Поле code одинаково на всех трёх эндпоинтах. В ответе Chat Completions и Responses оно лежит прямо в теле, в ответе Messages его заменяет error.type, разбор ниже.

HTTP	code	Когда
400	invalid_model, feature_not_supported, provider_bad_request	Запрос некорректен или запрошенная возможность не поддерживается
401	authentication_required, invalid_api_key	Нет ключа или ключ неверный. На двух старых поверхностях тело подменяется на {"error":"unauthorized"} и кода в нём нет
402	insufficient_funds	Не хватает кредитов на запрос
403	policy_violation	Запрос заблокирован политикой доступа
403	dlp_violation	Запрос заблокирован DLP, см. Плагины
403	provider_forbidden	Провайдер отказал по содержимому запроса
404	model_not_found	Модели нет в каталоге
408	provider_timeout	Модель не ответила за отведённое время
413	payload_too_large, file_too_large, text_content_too_large	Превышен размер тела, вложения или текстового блока, см. Лимиты
413	provider_payload_too_large	Лимит провайдера на эту модель ниже нашего, и запрос в него не поместился
422	validation_error	Запрос не прошёл валидацию (например, model не в формате <провайдер>/<модель>)
429	provider_rate_limited	Превышен лимит запросов
429	api_key_limit_exceeded	Достигнут лимит расходов по ключу. Время сброса счётчика в extra.reset_at
500	internal_service_error	Внутренняя ошибка
502	provider_unavailable, provider_model_down	Модель временно недоступна
503	service_unavailable, circuit_breaker_open	Роутер под нагрузкой или защита от лавины отказов. В заголовках бывает Retry-After
503	dlp_policy_unavailable	Политику DLP для ключа не удалось получить. Повторяемо, интервал в Retry-After
503	dlp_unavailable	В запросе есть plugins.dlp, а DLP не включён. Повтор не поможет

У модели waibee/auto есть свои коды 422 (auto_routing_no_match, auto_routing_request_too_large, auto_routing_caching_unavailable, auto_routing_missing_context), см. Autorouting.

Типы Messages

HTTP	error.type	Когда
400, 413, 422	invalid_request_error	Запрос некорректен или слишком большой
402, 429	rate_limit_error	Лимит запросов или нехватка кредитов
403	permission_error	Запрос заблокирован политикой доступа, DLP или модерацией провайдера
404	not_found_error	Модели нет в каталоге
408, 500, 503	api_error	Таймаут модели, внутренняя ошибка или недоступная политика DLP
502	overloaded_error	Модель временно недоступна

Тип не однозначен, поэтому ветвиться нужно по code. Один permission_error покрывает и policy_violation, и dlp_violation. И наоборот: у двух 503 типы разные, dlp_policy_unavailable приходит как api_error, потому что его лечит повтор, а dlp_unavailable как invalid_request_error, потому что повтор его не лечит.

500 в схеме не объявлен ни на одном эндпоинте: необработанная ошибка это наш дефект, а не обещание клиенту. Прийти он всё равно может, поэтому в таблице он есть.

Исключение: на /v1/chat/completions и /v1/messages отказ по API-ключу приходит короткой формой {"error":"unauthorized"} с кодом 401. На /v1/responses он приходит в общем формате.

Типы Responses

/v1/responses использует ту же схему типов с одной заменой: overloaded_error в ней нет, и 502 приходит как api_error. Рядом с типом всегда лежит code из таблицы выше, так что разбирать можно по любому из двух полей.

HTTP	error.type	Когда
400, 413, 422	invalid_request_error	Запрос некорректен или слишком большой
402, 429	rate_limit_error	Лимит запросов или нехватка кредитов
403	permission_error	Запрос заблокирован политикой доступа, DLP или модерацией провайдера
404	not_found_error	Модели нет в каталоге
408, 500, 502, 503	api_error	Таймаут модели, её недоступность или внутренняя ошибка

Исключение то же, что и на messages: dlp_unavailable это 503, но приходит как invalid_request_error, потому что запрос без работающей проверки принять нельзя.

Поле param называет параметр, из-за которого запрос отклонён, и приходит не всегда, см. Формат Responses.

Что делать

У каждого пункта свой якорь, так что на разбор конкретной ошибки можно дать прямую ссылку, например /router/errors/#api_key_limit_exceeded.

unauthorized

401. Ключ отсутствует, просрочен или неверен. Проверьте заголовок и сам ключ, см. Аутентификация. На /v1/chat/completions и /v1/messages тело короткое, {"error":"unauthorized"}, и поля code в нём нет. На /v1/responses приходит обычный конверт с code: authentication_required или invalid_api_key.

insufficient_funds

402. На запрос не хватает средств. Пополните баланс, повторы не помогут.

model_not_found

404. Модели нет в каталоге вашего ключа. Сверьте идентификатор с GET /v1/models, см. Модели.

validation_error

422. Запрос не прошёл валидацию. В extra.errors указано конкретное поле: чаще всего это имя модели без префикса провайдера или превышение лимита на число сообщений или инструментов, см. Лимиты.

feature_not_supported

400. Запрошена возможность, которую роутер не отдаёт: серверный инструмент провайдера или уровень усилий max на /v1/chat/completions. См. Вызов инструментов и Reasoning.

provider_rate_limited

429. Модель ограничила частоту обращений. Повторяйте с экспоненциальной задержкой, при постоянной нагрузке распределяйте её по моделям, см. Лимиты.

api_key_limit_exceeded

429. Достигнут лимит расходов по ключу за период. В extra.reset_at время сброса счётчика: до него повторы бессмысленны. Нужен другой ключ или увеличенный лимит.

policy_violation

403. Запрос заблокирован политикой доступа: например, модель не разрешена для вашей группы.

dlp_violation

403. Запрос заблокирован DLP, потому что в нём нашлись чувствительные данные. Находки перечислены в extra.dlp (в формате Anthropic в details.dlp), см. Плагины.

Причина в содержимом запроса, а не в правах ключа: статус тот же, что у policy_violation, а исправление другое. Уберите из запроса найденное или замените на заглушку. Другой ключ не поможет.

Проверка может оказаться шире того, что вы прислали в plugins.dlp, и даже сработать без этого поля: у ключа бывает своя политика, и она применяется как минимум, см. Политика API-ключа.

dlp_policy_unavailable

503. Политику DLP для вашего ключа не удалось получить, поэтому запрос отклонён, а не пропущен без проверки. Повторите через интервал из Retry-After.

dlp_unavailable

503. Запрос принёс plugins.dlp, а DLP не включён. Повторы бессмысленны: уберите поле или обратитесь в поддержку.

payload_too_large

413. Запрос не прошёл по размеру: всё тело, отдельное вложение или текстовый блок. Отдельные коды file_too_large и text_content_too_large говорят, что именно превышено. Значения в Лимитах.

provider_forbidden

403. Провайдер отказался обрабатывать содержимое запроса: обычно это срабатывание его собственной модерации. Отказ относится к тексту, а не к вашему ключу и не к вашим правам. Перефразируйте запрос или выберите другую модель.

provider_payload_too_large

413. Запрос прошёл наши лимиты, но не прошёл лимит провайдера: у отдельных моделей он ниже. Сократите ввод или возьмите модель с большим контекстом.

provider_timeout

408. Модель не ответила за отведённое время. Повторите; на reasoning-моделях с высоким уровнем усилий это ожидаемо чаще, см. Reasoning.

provider_unavailable

502. Провайдер не обслужил запрос: модель недоступна, перегружена, либо проблема на нашей стороне доступа к нему. Повторите; если повторяется на одной модели, попробуйте другую, а если на всех, напишите в поддержку. Тот же смысл у provider_model_down.

service_unavailable

503. Роутер под нагрузкой, либо сработала защита от лавины отказов (circuit_breaker_open). Если в ответе есть Retry-After, повторите через указанный интервал.

internal_service_error

500. Ошибка на нашей стороне. Повторите запрос; если повторяется, обратитесь в поддержку и приложите id ответа или время запроса.

auto_routing_*

422. Ошибки подбора модели для waibee/auto, разобраны в Autorouting.