Ошибки

Ответ с ошибкой содержит объект error:

Поле

Тип

Описание

code

string

Код ошибки из таблиц ниже. Опирайтесь в коде на него

message

string

Текст ошибки для человека; может меняться

details

object

Только у invalid_request: какой параметр не прошёл проверку и почему (параметр -> причина)

{
  "error": {
    "code": "dialog_not_found",
    "message": "Диалог не найден"
  }
}

HTTP-статус ответа всегда соответствует коду ошибки, как указано в таблицах.

Общие ошибки

Код

HTTP

Когда возникает

invalid_request

400

Параметр, которого нет в описании метода; обязательный параметр не передан; значение неверного типа или вне границ

invalid_api_key

401

Ключ не передан, не найден или другого вида: ключ агента в методе баз знаний или наоборот

api_disabled

403

Доступ по API выключен у агента или базы знаний

access_denied

403

Действие запрещено по иной причине

not_found

404

Такого пути в API нет

method_not_allowed

405

Метод не поддерживается для этого пути

rate_limited

429

Превышен лимит запросов — повторите запрос позже

credits_exhausted

429

Закончились e^кредиты пространства; текст ошибки называет, когда доступ восстановится

internal_error

500

Непредвиденная ошибка — повторите запрос позже

Агент, диалоги и сообщения

Код

HTTP

Когда возникает

agent_unavailable

400

Агент не настроен, не опубликован или недоступен на платформе

unsupported_agent_type

400

Метод вызван для агента, тип которого API не обслуживает (все методы, кроме карточки агента)

dialog_not_found

404

Диалога нет или он принадлежит другому user_id

message_not_found

404

Сообщения нет или оно в диалоге другого user_id

model_unavailable

400

Модель агента не настроена или не поддерживается

generation_failed

400

Ошибка модели или агента при генерации ответа

generation_timeout

504

Истекло время генерации ответа

agent_step_limit_reached

400

Агент исчерпал лимит шагов

tool_call_too_large

400

Вызов инструмента не уместился в лимит ответа модели

tool_access_denied

403

Инструмент агента недоступен пространству

document_too_large

400

Файл в сообщении не помещается в контекст модели

document_unreadable

400

Не удалось извлечь текст из файла в сообщении

follow_up_questions_disabled

400

У агента выключены «Подсказки вопросов»

Ошибки от model_unavailable до document_unreadable возникают при отправке сообщения. Если ошибка обнаружена до начала ответа, API отвечает HTTP-ошибкой с этим кодом — и при stream: true тоже, а сообщение в историю не попадает. Если ошибка случилась во время генерации, без потока она приходит HTTP-ответом, в потоке — событием generation.failed, а в истории диалога — в поле error сообщения. Подробнее — на странице Отправка сообщений.

Файлы

Код

HTTP

Когда возникает

no_file

400

Файл не передан

file_too_large

413

Файл больше допустимого размера; текст ошибки называет предел в МБ

unsupported_file_type

415

Формат файла не принимается, или у файла в запросе не указан тип содержимого (Content-Type)

file_not_found

404

Файла нет, или этот user_id его не загружал и в его диалогах его нет

invalid_file_id

400

В сообщении передан идентификатор файла, который этот user_id не загружал

file_upload_disabled

400

В сообщении есть файлы, а загрузка файлов у агента выключена

file_type_blocked

400

Тип файла не разрешён настройками агента

too_many_files

400

Файлов в сообщении больше, чем разрешено настройками агента, или в поле file передано больше одного файла; текст ошибки называет предел

Ошибки обработки файла

Приходят в поле error статуса файла, когда status — failed.

Код

Когда возникает

no_audio_track

В видео нет аудиодорожки

video_corrupted

Видеофайл повреждён

audio_too_long

Аудиодорожка длиннее допустимого

processing_timeout

Обработка не уложилась в отведённое время

processing_failed

Обработка не удалась по иной причине

Базы знаний

Код

HTTP

Когда возникает

knowledge_base_not_found

404

Базы знаний нет, она в другом пространстве или недоступна ключу

knowledge_base_name_taken

400

База знаний с таким названием в пространстве уже есть

knowledge_base_type_immutable

400

Попытка сменить тип базы знаний

knowledge_base_in_use

400

Удаление системной базы знаний, которую используют агенты

knowledge_base_model_unavailable

400

Модель эмбеддингов базы знаний недоступна: нельзя изменить текст фрагмента, включить, выключить или удалить документ или фрагмент

knowledge_base_full

400

В файловой базе знаний уже столько файлов, сколько она вмещает; текст ошибки называет предел

knowledge_base_storage_full

400

Документ не помещается в объём файловой базы знаний; текст ошибки называет предел в МБ

document_limit_reached

403

Исчерпан лимит документов тарифа

storage_limit_reached

403

Исчерпан объём тарифа

document_not_found

404

Документа нет в этой базе знаний

document_processing

400

Документ ещё обрабатывается или переиндексируется после прошлого включения или выключения

document_archived

400

Изменение архивного документа базы знаний с поиском или его фрагмента

chunk_not_found

404

Фрагмента нет в этом документе

chunk_disabled

400

Изменение текста отключённого фрагмента без его включения в том же запросе

chunks_not_supported

400

Запрос к фрагментам документа файловой базы знаний: у неё фрагментов нет

tag_not_found

404

Тега нет

tag_name_taken

400

Тег с таким названием в пространстве уже есть

Если документ не удалось обработать, у него status — error, а в поле error — код document_processing_failed.