Ошибки и диагностика

примечание

Страница описывает ответы самого шлюза AIaaS. Примеры корректных запросов — в разделе Примеры подключения и использования.

С чего начать диагностику

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

export API_KEY="ваш_API_ключ"
export BASE_URL="https://<адрес, выданный при подключении>/v1"

curl -sS "$BASE_URL/models" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-AIN-USERNAME: ваш_логин" \
  -H "X-AIN-SOURCEID: название_системы"

Этот запрос отвечает сразу на три вопроса: жив ли ключ, доступен ли шлюз и разрешён ли вам нужный маршрут. Ответ содержит только те маршруты, которые открыты вашей лицензией, — он может быть короче общего каталога моделей, и это нормально.

Ошибки маршрутизации

Эти ошибки возвращает сам шлюз. Запрос до модели не доходит, потребление не списывается.

{"error": "nexus \"...\" not found"}

HTTP 400. Маршрут не существует либо не разрешён вашему ключу.

Что проверить:

• точное написание маршрута — сверьте с выводом GET /v1/models;
• на нужный ли эндпоинт отправлен запрос: у видео и изображений свои пути;
• не ушёл ли маршрут из вашей лицензии — если его нет в /v1/models, обратитесь в поддержку.

{"error": "unknown content-type"}

Не передан заголовок Content-Type: application/json. Возникает в том числе на GET-запросах к видео — им заголовок нужен так же, как POST-запросам.

parse request data: ... unexpected end of JSON input

Заголовок Content-Type: application/json передан, а тело запроса — нет. Шлюз ожидает тело даже там, где по привычке его не отправляют.

Чаще всего встречается на GET-запросах к видео: библиотека requests не отправляет тело в GET штатным способом. Используйте httpx с client.request("GET", ..., json=...) или curl.

{"error": "nexus not found"} при пустом теле {}

Тело запроса есть, но в нём нет поля model. Шлюз определяет маршрут по телу запроса, а не по URL, поэтому поле model обязательно в каждом запросе — включая опрос статуса и скачивание результата.

{"error": "invalid endpoint"}

Маршрут вызван по неподходящему пути. Типичный случай — попытка обратиться к видео-маршруту через /chat/completions или указать .videos_status в запросе на создание задания.

Каждому шагу соответствует свой маршрут:

Действие	Путь	Маршрут
Чат, в том числе Nano Banana	/chat/completions	*.chat_completions
Генерация изображения	/images	*.images
Постановка задания на видео	/videos	*.videos
Статус задания	/videos/{job_id}	*.videos_status
Скачивание видео	/videos/{job_id}/content	*.videos_content
Модели Yandex	/responses	yndx.*.responses
Векторизация	/embeddings	*.embeddings

Ошибки аутентификации

HTTP 401

Ключ неверен, неактивен или не передан. Проверьте заголовок Authorization: Bearer <ключ> — именно со словом Bearer и пробелом.

HTTP 500 {"error": "no key access_token"}

Шлюз не смог получить токен доступа у провайдера модели. Это не ошибка вашего запроса — обратитесь в поддержку, указав маршрут и время обращения.

Ошибки валидации

Если в ответе видна структура ошибки провайдера, значит запрос успешно прошёл маршрутизацию и был отклонён уже моделью. Это хороший признак: маршрут и ключ рабочие, поправить нужно тело запроса.

Ответ	Причина
Invalid input: expected string, received undefined с указанием "path": ["prompt"]	Не передано обязательное поле prompt
This model requires a prompt	То же для видео-маршрутов
Input required: specify "prompt" or "messages"	Для chat-маршрутов нужно поле messages

Прочие ситуации

Служебные ссылки из ответа не открываются

В ответе на опрос статуса видео приходят поля polling_url и unsigned_urls. Они ведут во внутреннюю инфраструктуру платформы и вашим ключом AIaaS не открываются — вернётся 401 или 404. Скачивайте результат только через шлюз, маршрутом *.videos_content.

Запрос завершается по таймауту

Генерация изображений и видео, OCR больших документов и транскрипция длинных записей выполняются дольше обычного чата. Рекомендуемые таймауты приведены в разделе Примеры подключения и использования.

Ответ с изображением приходит одним JSON, внутри которого картинка в base64, — он может весить 3–4 МБ. Клиент с коротким таймаутом или ограничением на размер ответа оборвёт соединение.

Модель отвечает, но потребление выше ожидаемого

В input-токены попадают не только видимый запрос пользователя, но и системный промпт, история диалога, RAG-контекст, содержимое документов и результаты предыдущих вызовов инструментов. Методика расчёта — в разделе Расчёт A-токенов.

Что приложить к обращению в поддержку

• маршрут из поля model;
• путь запроса и метод;
• полный текст ответа с ошибкой;
• дату и время обращения с указанием часового пояса;
• значения заголовков X-AIN-USERNAME и X-AIN-SOURCEID.

Ключ API в обращение не включайте.