Ошибки

Когда запрос завершается неудачно, API возвращает JSON конверт ошибки со стабильной формой. Ветвите обработку ошибок по машиночитаемым полям type и code — никогда по человекочитаемому message (который может меняться).

Конверт ошибки


{
  "error": {
    "type": "not_found_error",
    "code": "agent_not_found",
    "message": "No agent with that id exists.",
    "param": "agent_id"
  }
}

Поле	Тип	Значение
`type`	string	Одна из семи фиксированных категорий ниже. Сопоставляется со статусом HTTP.
`code`	string	Стабильный, машиночитаемый идентификатор каждой ошибки (например, `agent_not_found`).
`message`	string	Человекочитаемое описание. Только для отображения/логирования — не ветвите по нему.
`param`	string	(Необязательно) Поле запроса, вызвавшее ошибку, когда применимо.

Категории

Существует ровно семь категорий ошибок. Каждая сопоставлена с фиксированным статусом HTTP, поэтому категория и код статуса всегда согласованы.

`type`	Статус HTTP	Когда возникает	Примеры `code`
`authentication_error`	`401`	API key отсутствует, искажён, отозван или неизвестен.	`invalid_api_key`
`permission_error`	`403`	У key нет требуемого scope, или у создавшей роли нет сопоставленного права RBAC.	`invalid_scope`, `permission_denied`
`tier_error`	`403`	Ваш тариф не разрешает операцию, или настройка нарушает лимит тарифа.	`tier_limit`
`invalid_request_error`	`400`	Запрос был искажён или нарушил ограничение.	`invalid_cursor`, `invalid_upload`, `folder_name_exists`, `folder_not_empty`, `tag_name_exists`
`not_found_error`	`404`	В вашей организации нет ресурса с таким id.	`agent_not_found`, `document_not_found`
`rate_limit_error`	`429`	Вы превысили лимит запросов или запросов к agent вашего тарифа.	`rate_limit_exceeded`
`api_error`	`500`	Произошла непредвиденная ошибка на стороне upstream — повторите запрос.	`upstream_error`

Категории аддитивны и никогда не переназначаются — в будущем может быть добавлена новая категория, но существующая никогда не изменит смысл, поэтому ветвление по type безопасно.

Не найдено, никогда не между организациями

Id ресурса, принадлежащего другой организации, сообщается как 404 not_found_error, ровно так, как если бы он не существовал — API никогда не раскрывает существование ресурсов вне вашей организации через 403.

Исключение для дублирующей загрузки

Один ответ намеренно не является конвертом ошибки: когда загрузка документа совпадает с существующим документом, POST /knowledge/documents возвращает 409 со структурированным телом DuplicateDetected (несущим upload_session_id), а не конверт ошибки. Возобновите загрузку через POST /knowledge/documents/confirm-duplicate. Полный поток смотрите на странице документов Knowledge.


{
  "upload_session_id": "ups_abc123",
  "duplicate_of": ["doc_existing456"]
}