Перейти к основному содержимому

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

примечание

Страница описывает ответы самого шлюза 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. Он нужен в каждом запросе, в том числе при опросе статуса и скачивании видео.

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

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

Чаще всего встречается при опросе статуса и скачивании видео: эти шаги — тоже POST-запросы с телом {"model": "....videos_status"} или {"model": "....videos_content"}.

{"error": "nexus not found"} при пустом теле {} или запросе методом GET​

Шлюз определяет маршрут по полю model в теле POST-запроса, а не по URL. Поэтому поле model обязательно в каждом запросе — включая опрос статуса и скачивание результата. Если тела нет, в нём нет model или запрос отправлен методом GET, шлюз маршрут не находит. Опрос статуса и скачивание видео отправляйте методом POST — пример в разделе Примеры подключения и использования.

{"error": "invalid endpoint"}​

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

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

ДействиеПутьМаршрут
Чат, в том числе Nano Banana/chat/completions*.chat_completions
Генерация изображения/images*.images
Постановка задания на видео/videos*.videos
Статус заданияPOST /videos/{job_id}*.videos_status
Скачивание видеоPOST /videos/{job_id}/content*.videos_content
Модели Yandex/chat/completionsyndx.*.chat_completions
Векторизация/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-контекст, содержимое документов и результаты предыдущих вызовов инструментов. Цены входа и выхода по каждой модели — на странице Модели и поставщики.

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

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

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