Список ошибок

Справочник ошибок API Царь Роутера - HTTP-коды, типы и сообщения, которые может вернуть /v1, с пояснениями на русском

Все ошибки /v1 возвращаются в OpenAI-совместимом формате:

{"error": {"message": "...", "type": "...", "param": null, "code": "..."}}

Поля устроены механически, поэтому их не нужно запоминать по каждой ошибке:

type однозначно выводится из HTTP-кода: 400 → invalid_request_error, 401 → authentication_error, 402 → insufficient_quota, 403 → permission_error, 404 → not_found_error, 429 → rate_limit_error, 500/502/503 → server_error, прочие (413, 422) → api_error. В таблицах ниже колонка type опущена - смотрите на HTTP-код.
code - HTTP-код строкой ("400", "429", …). Исключение: ошибки валидации тела запроса приходят с code: "invalid_value".
param практически всегда null; у ошибок валидации тела (invalid_value) поля param нет вовсе.
Сам API код 504 не отдаёт: таймауты провайдеров превращаются в 502/503. Единственный источник 504 - транспортный слой, если ответ на /v1/ висит дольше 600 секунд.

В сообщениях ниже {в фигурных скобках} - подставляемые значения.

Общие ошибки - любой эндпоинт `/v1`

Авторизация

code	message	Описание
401	`Invalid API key`	Неверный или несуществующий API-ключ. Проверьте Bearer-токен.
401	`API key not found`	Ключ был удалён или деактивирован в момент обработки запроса.
401	`API key has expired`	Истёк срок действия ключа.
401	`Not authenticated`	Заголовок `Authorization: Bearer <key>` отсутствует или пустой.
403	`API key is disabled. Enable it in the dashboard to resume use.`	Ключ заморожен владельцем в личном кабинете. Включите его в дашборде.

Баланс и бюджет ключа

code	message	Описание
402	`Account balance too low: {balance} ₽ available, minimum 1 ₽ required. Add funds to your account.`	На счёте меньше 1 ₽. Пополните баланс.
402	`Insufficient balance for this request: estimated up to {est} ₽, available {balance} ₽. Add funds and retry.`	Баланса не хватит на данный запрос. Пополните и повторите.
402	`API key budget limit reached: {spent} of {limit} ₽ spent. Increase this key's limit in the dashboard or use another key.`	Исчерпан денежный лимит самого ключа (не баланс аккаунта). Поднимите лимит ключа или используйте другой.

Все ответы 429 - rate_limit_error; несут заголовки Retry-After (секунды до сброса окна; у лимита одновременных потоков - фиксированные 5 с) и x-ratelimit-*, а к сообщению добавляется Retry after {n} seconds. Подробнее о самих лимитах - в разделе Лимиты.

code	message	Описание
429	`Rate limit exceeded: {N} requests/minute.`	Базовый минутный лимит ключа.
429	`Rate limit exceeded for {type} models: {N} requests/minute.`	Минутный лимит уровня на данный тип моделей.
429	`Rate limit for free models exceeded: {N} requests/minute.`	Минутный лимит запросов к бесплатным моделям.
429	`Daily cap for free models reached: {N} requests/day, resets at midnight Europe/Moscow.`	Суточный лимит бесплатных моделей; счётчик сбрасывается в полночь по Москве.
429	`Rate limit exceeded: {N} requests/minute for this endpoint.`	Лимит справочных эндпоинтов: `GET /v1/models`, `/v1/key`, `/v1/stats`.

Отдельный транспортный случай: при потоке заметно чаще ~30 запросов в секунду с одного IP ответ 429 отдаёт nginx HTML-страницей - без OpenAI-конверта и без Retry-After (аналогично HTML-413 из таблицы ниже). Снизьте частоту запросов с одного адреса.

Модель не найдена

Одна схема на все типы моделей: модели с таким ID нет в каталоге, или она не относится к типу эндпоинта.

code	message	Описание
400	`{Тип} model '{model}' not found. Available: {список}`	Все специализированные эндпоинты. Префикс `{Тип}` соответствует эндпоинту: `Embedding` (/v1/embeddings), `Reranker` (/v1/rerank), `Image` (/v1/images/generations), `Image enhancement` (/v1/images/enhance), `Classification` (/v1/classify), `Speech` (/v1/audio/speech), `STT` (/v1/audio/transcriptions - без списка `Available` и без точки на конце), `Sentiment` (/v1/audio/sentiment), `AI-check` (/v1/ai/check).
400	`Model '{model}' not found. Use GET /v1/models to list available models.`	`/v1/chat/completions`.
404	`Model '{model}' not found`	`GET /v1/models/{id}`: запрос модели по ID, которого нет в каталоге.

Валидация тела запроса

code	message	Описание
400	`{источник} -> {поле}: {текст ошибки}`	Невалидное тело запроса: нет обязательного поля или неверный тип. Несколько ошибок склеиваются через `;`. У этих ответов `code: "invalid_value"`. Пример: `body -> messages: List should have at least 1 item after validation, not 0`.

Доступность модели и провайдеров

code	message	Описание
4xx	`Request for model '{model}' was rejected by the provider. Please verify your request parameters.`	Провайдер отверг запрос как невалидный; HTTP-код наследуется от провайдера. Обычно в `message` приходит текст самого провайдера; показанный шаблон - резервный, когда текста нет. В чате возможен краткий вариант `Request rejected by the provider.`
502	`All providers for '{model}' are currently unavailable. Retry shortly or contact support if it persists.`	`/v1/embeddings`, `/v1/rerank`, `/v1/images/generations`, `/v1/chat/completions` без fallback-цепочки: все провайдеры недоступны.
502	`All providers failed for model chain [{модели}]`	`/v1/chat/completions` с fallback-цепочкой или стримингом: все маршруты недоступны. Повторите позже или смените модель.
503	`No provider available for '{model}'. All providers are currently unavailable. Retry shortly or contact support if it persists.`	`/v1/ai/check`, `/v1/images/enhance`, `/v1/classify`, синтез, распознавание и тональность речи: все провайдеры недоступны.
503	`Model '{model}' temporarily unavailable: pricing not configured. Contact support.`	У модели временно не настроен тариф. Повторите позже или обратитесь в поддержку.
503	`Model '{model}' is temporarily disabled for maintenance.`	Модель временно отключена на обслуживание. Выберите другую или повторите позже.

Стриминг (`stream: true`)

code	message	Описание
402	`Insufficient balance to start streaming: required {hold} ₽, available {balance} ₽. Add funds or use another key.`	Баланса не хватит при старте потокового ответа.
429	`Concurrent stream limit reached: {N} simultaneous streams. Wait for a running stream to finish and retry.`	Лимит одновременных потоков уровня (см. Лимиты).

Ошибка до первого чанка приходит обычным JSON-конвертом. Если сбой случился после первого чанка (HTTP 200 уже отправлен) - поток обрывается без завершающего [DONE] и без error-чанка. Отсутствие [DONE] - признак оборванного ответа.

Валидация параметров эндпоинтов

Эндпоинт	code	message	Описание
`/v1/images/generations`	400	`Parameter 'prompt' is required for image generation.`	Пустой `prompt`.
`/v1/images/generations`	400	`Only n=1 is supported: one image per request.`	Одна картинка за запрос.
`/v1/images/generations`	400	`Prompt too long: maximum {max} characters, got {n}.`	Слишком длинный промпт.
`/v1/images/enhance`	400	`Parameter 'image' is required (empty file).`	Передан пустой файл изображения.
`/v1/images/enhance`	400	`Only JPEG and PNG images are supported.`	Поддерживаются только JPEG и PNG.
`/v1/images/enhance`	400	`Parameter 'rfactor' must be 2 or 4.`	Коэффициент апскейла только 2 или 4.
`/v1/images/enhance`	400	`Parameter 'rtype' must be 'photo' or 'art'.`	Тип апскейла только `photo` или `art`.
`/v1/images/enhance`	413	`Image too large: maximum {N} MB, got {x} MB.`	Файл больше 10 МБ; `type: api_error`. На практике такой файл обычно отсекает nginx ещё раньше - тогда придёт HTML-413 (строка ниже), а не JSON.
`/v1/classify`	400	`Parameter 'text' is required for classification.`	Пустой `text`.
`/v1/classify`	400	`Provide between 2 and 20 labels, got {n}.`	Нужно от 2 до 20 меток.
`/v1/audio/speech`	400	`Parameter 'input' is required for speech synthesis.`	Пустой `input`.
`/v1/audio/speech`	400	`Input too long: maximum {max} characters, got {n}.`	Лимит 5000 символов.
`/v1/audio/transcriptions`	400	`Файл больше лимита модели '{model}': {x} МБ > {N} МБ.`	Размер файла сверх лимита выбранной модели (у каждой свой: Yandex async - 60 МБ, T-Bank - 32, VK - 20, Yandex sync - 1; см. карточку модели).
`/v1/audio/transcriptions`	400	`Аудио длиннее лимита модели '{model}': {n} с > {N} с.`	Длительность записи сверх лимита модели (напр. Yandex sync - 30 с, Yandex async - 40 мин, VK - 5 мин).
`/v1/audio/transcriptions`	400	`Параметр 'roles' доступен только вместе с diarize=true.`	Разметку ролей говорящих (Nexara) можно запросить только при включённой диаризации `diarize=true`.
любой	413	- (HTML nginx)	Тело запроса больше транспортного лимита: 60 МБ для `/v1/audio/transcriptions`, 10 МБ для остальных эндпоинтов. Ответ отдаёт nginx без JSON-тела.
`/v1/ai/check`	400	`Text too short: AI-content detection requires at least {min} words, got {n}.`	Текст слишком короткий для детекции.
`/v1/ai/check`	400	`This detector supports Russian text only (>=50% Cyrillic), got {x}%.`	Детектор работает только с русским текстом.

Распознавание речи: форматы аудио

/v1/audio/transcriptions; все ошибки ниже - 400 invalid_request_error.

Модель	message
`yandex/speech-to-text`	`yandex/speech-to-text (синхронный) не принимает MP3 — только WAV (PCM) и OGG/Opus. Для MP3 используйте yandex/speech-to-text-async.`
`yandex/speech-to-text`	`Некорректный WAV-файл (ожидается PCM).`
`yandex/speech-to-text`	`yandex/speech-to-text принимает только моно (1 канал). Для многоканального аудио используйте yandex/speech-to-text-async.`
`yandex/speech-to-text`	`WAV должен быть 16-бит PCM (LINEAR16).`
`yandex/speech-to-text`	`Частота дискретизации {rate} Гц не поддерживается (допустимо: {список}).`
`yandex/speech-to-text`	`Неизвестный формат аудио: yandex/speech-to-text принимает WAV (PCM) и OGG/Opus.`
`yandex/speech-to-text`	`yandex/speech-to-text (синхронный) принимает до 1 МБ аудио (WAV считается по PCM-данным). Для длинных записей используйте yandex/speech-to-text-async.`
`yandex/speech-to-text-async`	`Неизвестный формат аудио: yandex/speech-to-text-async принимает MP3, WAV и OGG/Opus.`
`yandex/speech-to-text-async`	`Аудио с {n} каналами не поддерживается — максимум 2 (моно или стерео).`
обе модели Yandex	`Yandex STT: {сообщение провайдера}` - проброс ошибки входных данных от Яндекса (например, битый файл).
`tbank/speech-to-text`	`Invalid MP3: could not determine sample rate and channels.` - битый MP3; пришлите корректный MP3 или WAV (PCM).
`tbank/speech-to-text`	`Unsupported audio format. Use WAV (PCM) or MP3.`

Потоковое распознавание речи (WebSocket)

/v1/realtime/transcriptions - WebSocket-эндпоинт (формат событий OpenAI Realtime transcription). Ошибки приходят двумя способами:

1. Отказ на этапе подключения (handshake). Неверный или отсутствующий API-ключ - соединение отклоняется с HTTP 403 ещё до установки WebSocket.

2. Событие error + код закрытия. Внутри сессии сервер шлёт событие {"type": "error", "error": {"code": ..., "message": ...}}; фатальные ошибки дополнительно закрывают соединение со стабильным close-кодом:

close-код	code	Описание
4001	`invalid_api_key`	Ключ не прошёл проверку уже после подключения (например, отключён владельцем).
4002	`model_not_found`	Модель не задана, не существует или не поддерживает потоковое распознавание.
4003	`insufficient_balance`	Баланса не хватает даже на минимальную сессию. Пополните счёт.
4004	`unsupported_audio_format`	Формат аудио не поддерживается: нужен `audio/pcm` (PCM16LE), частота из списка 8000, 16000, 22050, 32000, 44100, 48000 Гц.
4008	`session_limit_exceeded`	Исчерпан лимит аудио-секунд или общей длительности сессии (см. Лимиты). Откройте новую сессию.
4009	`idle_timeout`	Нет сообщений от клиента дольше таймаута бездействия - сессия закрыта.
4010	`concurrent_session_limit`	Достигнут лимит одновременных потоковых сессий вашего уровня.
4029	`rate_limit_exceeded`	Слишком частые открытия сессий (rpm-лимит типа).
1011	`upstream_error`	Сбой провайдера распознавания. Повторите попытку.
1013	`model_disabled`	Модель временно отключена на обслуживание.

Нефатальные ошибки (сессия продолжает работать, приходит только событие error):

code	Описание
`model_not_set`	Аудио прислано до выбора модели (`?model=` или `session.update`).
`input_audio_buffer_commit_empty`	`commit` без аудио в буфере.
`commit_too_short`	`commit` фразы короче минимума - продолжайте слать аудио перед `commit`.
`audio_chunk_too_large`	Слишком большой чанк в одном `append` - шлите короче (~200 мс).
`clear_not_supported`	`input_audio_buffer.clear` не поддерживается - аудио уходит в распознавание сразу.
`format_locked` / `model_locked`	Формат/модель нельзя менять после начала передачи аудио.
`invalid_audio` / `invalid_json`	`audio` не base64 / событие не JSON.
`empty_audio`	`append` с пустым `audio` - пришлите байты PCM16LE.
`invalid_payload` / `unknown_event`	Прислан бинарный фрейм вместо JSON / неизвестный тип события.

Ошибки моделей

code	message	Описание
400	`Invalid image input: {детали}`	Распознавание (OCR Yandex) и зрение (VK) в чате: изображение нужно передавать как base64 data URI (JPEG/PNG).
400	`Unknown VK Cloud model: {model}`	Неизвестная VK Cloud Vision-модель.
400	`VK Cloud enhance error: {детали}`	VK (обработка фото): ошибка параметров обработки изображения.
422	текст причины от модели	Kandinsky (GigaChat) сгенерировал отказ по контент-политике при генерации изображения. ⚠️ Запрос тарифицируется. Измените промпт. `type: api_error`.
502	`VK Cloud Vision error: {детали}`	Сбой обработки на стороне VK (зрение / апскейл / реставрация). Дословно доходит при стриминге или fallback-цепочке чата; в остальных случаях превращается в общие 502/503 из раздела «Доступность».