Ошибки LLM в Copilot

Copilot в Building OS обращается к той LLM, которую здание подключило в Настройки здания → ИИ-ассистент. Любой сбой на этом пути — неверный ключ, исчерпанный лимит, недоступный self-hosted-эндпоинт — преобразуется в один из стабильных кодов ниже прежде, чем попасть в интерфейс или API. Пользователь никогда не видит сырой ответ провайдера или 500: он видит заголовок и описание кода и ссылку Подробнее на раздел этой страницы.

Как ошибки доходят до вас

• В Building OS панель Copilot показывает карточку ошибки. Панель Последние вызовы в Настройки здания → ИИ-ассистент хранит последние вызовы по зданию: провайдер, модель, задержка и код ошибки.
• Через API неудавшийся запрос к чату отвечает HTTP-статусом кода и таким телом:

{
  "code": "RATE_LIMITED",
  "title": "Rate limited",
  "detail": "The provider is throttling your requests. Wait a moment and try again, or upgrade your plan.",
  "helpUrl": "https://developers.tango.vision/reference/llm-errors#rate-limited"
}

code стабилен, на него можно завязывать логику. title и detail — текст, он может меняться. Если провайдер вернул JSON с ошибкой, в detail попадает его собственное сообщение, и открывать консоль провайдера не нужно.

• Проверка подключения (в мастере добавления LLM или POST …/llm-configs/:id/test) отвечает { ok: false, errorCode, message } с теми же кодами.

Код	HTTP-статус
INVALID_API_KEY	401
MODEL_NOT_FOUND	404
RATE_LIMITED	429
PROVIDER_UNREACHABLE	502
PROVIDER_TIMEOUT	504
PROVIDER_INTERNAL_ERROR	502
UNSUPPORTED_FEATURE	422
BAD_REQUEST	400
NOT_CONFIGURED	424
ENCRYPTION_UNAVAILABLE	503
UNKNOWN	500

Неверный API-ключ

INVALID_API_KEY — провайдер ответил 401 или 403.

• Вставьте ключ заново в Настройки здания → ИИ-ассистент. Ключи хранятся зашифрованными и больше не показываются, поэтому опечатка проявится только при первом вызове.
• Убедитесь, что ключ относится к тому же аккаунту и региону, что и введённый базовый URL. Ключ из EU-консоли провайдера не работает с его US-эндпоинтом.
• Self-hosted-эндпоинты (свой эндпоинт), которым ключ не нужен, всё равно получают bearer-токен-заглушку; если ваш шлюз отвергает неизвестные токены, разрешите заглушку или выпустите настоящий ключ.
• Провайдерам, которые аутентифицируют не через Authorization: Bearer (например, api-key у Azure OpenAI), нужный заголовок задаётся через extraHeaders при создании конфигурации через API.

Модель недоступна

MODEL_NOT_FOUND — провайдер ответил 404.

• Имя модели написано с ошибкой, модель снята с поддержки или не включена для этого аккаунта или тарифа. Выберите модель из списка провайдера.
• Неверный базовый URL тоже даёт 404. Платформа добавляет к базовому URL /chat/completions, поэтому https://host/v1 — правильно, а https://host или https://host/v1/chat/completions — нет. Сначала исправьте базовый URL, потом меняйте модель.

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

RATE_LIMITED — провайдер ответил 429.

• Подождите и повторите; большинство лимитов — поминутные.
• Поднимите квоту или тариф аккаунта либо переведите здание на ключ с собственной квотой. Несколько зданий на одном ключе делят один лимит.

Провайдер недоступен

PROVIDER_UNREACHABLE — платформа вообще не смогла установить соединение (не разрешилось DNS-имя, соединение отклонено или сброшено).

• Проверьте хост в базовом URL на опечатки.
• Запрос уходит с API-сервера платформы, а не из вашего браузера. Self-hosted-модель, которая отвечает на вашем ноутбуке или внутри частной сети, должна быть доступна из кластера, где работает tv-api. localhost в базовом URL — это API-сервер, а не ваша машина.
• Проверьте страницу статуса провайдера и правила исходящего трафика.

Провайдер отвечает слишком долго

PROVIDER_TIMEOUT — полный ответ не пришёл в отведённое время (60 с на вызов чата, 10 с на проверку подключения), либо провайдер ответил 408 или 504.

• Попробуйте модель меньше или быстрее либо регион ближе к кластеру.
• Self-hosted-модели, которые загружаются в память при первом запросе, часто один раз не укладываются в лимит, а потом работают; запустите Проверить подключение дважды, прежде чем разбираться глубже.

Ошибка провайдера

PROVIDER_INTERNAL_ERROR — провайдер ответил 5xx (кроме 504).

• Обычно временно; повторите чуть позже.
• Если повторяется, посмотрите страницу статуса провайдера. Со стороны платформы на этот исход повлиять нельзя.

Функция не поддерживается

UNSUPPORTED_FEATURE — у провайдера или модели нет того, что нужно Copilot.

• Copilot управляет зданием через вызовы инструментов (function calling в стиле OpenAI). Выберите модель, которая их поддерживает; многие небольшие self-hosted-модели — нет.
• Нативные провайдеры Anthropic, Gemini и GigaChat пока не реализуют потоковую передачу. Copilot использует непотоковые вызовы, так что это касается только интеграций, которые запрашивают стриминг явно.

Неверный запрос

BAD_REQUEST — провайдер отклонил запрос другим кодом 4xx.

• В detail — собственное сообщение провайдера, если он его прислал.
• Типичные причины: параметр, который модель не принимает (temperature, max tokens), запрос больше контекстного окна модели или шлюз, ожидающий другой диалект запроса. Вызов есть в панели Последние вызовы.

ИИ-ассистент не настроен

NOT_CONFIGURED — к зданию не подключена ни одна LLM, а у платформы нет резервной конфигурации.

• Откройте Настройки здания → ИИ-ассистент и добавьте провайдера. Copilot использует конфигурацию по умолчанию; сохранённой, но не выбранной по умолчанию, недостаточно.
• Операторы платформы могут задать резервную конфигурацию на уровне окружения (LLM_PROVIDER, LLM_API_KEY, LLM_BASE_URL, LLM_MODEL у tv-api) — она действует для всех зданий без собственной конфигурации.

LLM-мост недоступен

ENCRYPTION_UNAVAILABLE — платформа не смогла расшифровать сохранённый API-ключ.

• На API-сервере отсутствует LLM_CONFIG_ENCRYPTION_KEY или он изменился после сохранения конфигурации. Ключи, зашифрованные старым значением, прочитать нельзя.
• Администратор здания восстанавливает работу, введя API-ключ заново в Настройки здания → ИИ-ассистент: он будет зашифрован текущим ключом платформы. Если повторяется — обратитесь к администратору платформы.

Непредвиденная ошибка

UNKNOWN — сбой, который ни одно из правил выше не распознало.

• Подробности записаны вместе с вызовом в панели Последние вызовы и в логах API-сервера.
• Сообщите о ней с id здания и временем вызова; каждая воспроизводимая UNKNOWN становится именованным кодом.

Добавление кода

Коды живут в LlmErrorCode в tv-api (src/copilot/providers/), и каждый провайдер сопоставляет свои низкоуровневые сбои одному из них. Новому коду в одном изменении нужны: член union-типа, запись в ERROR_CATALOG с helpUrl на эту страницу и раздел на этой странице с якорем — кодом в lower-kebab-case (PROVIDER_TIMEOUT → #provider-timeout). Тесты каталога проверяют форму URL; эта страница — то, куда ссылка должна вести.