Коды ошибок

Справочник кодов ошибок API Вайбкод: единый формат ответа, перечень кодов, типичные причины и способы устранения. Применяется ко всем эндпоинтам /v1/....

Разделы документации

• Авторизация, ключи и права — MISSING_API_KEY, INVALID_API_KEY, TOKEN_MISSING, SCOPE_DENIED, BITRIX_ACCESS_DENIED, WRITE_BLOCKED_READONLY_KEY
• Запрос и данные — VALIDATION_ERROR, INVALID_PARAMS, MISSING_REQUIRED_FILTER, BATCH_LIMIT_EXCEEDED, ENTITY_NOT_FOUND
• Биллинг, тариф и подписка — BILLING_EXHAUSTED, COMMERCIAL_PLAN_REQUIRED, TRIAL_EXPIRED, B24_MARKET_SUBSCRIPTION_REQUIRED, B24_MARKET_TRIAL_USED, INT_TARIFF_REQUIRED
• Лимиты, очереди и паузы — RATE_LIMITED, ERROR_LOOP_DETECTED, QUEUE_OVERFLOW, QUEUE_TIMEOUT, TIMEOUT_QUARANTINE, OPERATION_TIME_LIMIT
• Битрикс24 и платформа — BITRIX_ERROR, METHOD_NOT_YET_AVAILABLE, BITRIX_UNAVAILABLE, BITRIX_TIMEOUT, INTERNAL_ERROR
• Повторы и обработка ошибок в коде — когда повторять запрос, а когда сначала перечитать сущность

Формат ответа при ошибке

Каждый ответ с ошибкой возвращается в едином виде. error — объект.

{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Элемент не найден"
  }
}

Пример ответа с дополнительным полем hint (429 RATE_LIMITED) — срок повтора здесь приходит только заголовком Retry-After: 2:

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "QUERY_LIMIT_EXCEEDED",
    "hint": "Wait 1-2 seconds and retry. Use POST /v1/batch to combine up to 50 calls in 1 request."
  }
}

HTTP-заголовок Retry-After дублирует значение error.retryAfter для совместимости со стандартом HTTP. Есть отказы, где поле в теле не приходит, а заголовок — приходит, поэтому опирайтесь на заголовок.

Сводная таблица кодов

Таблица покрывает основные коды, которые встречаются на любом эндпоинте API Вайбкод. Доменные коды (BOT_NOT_FOUND, SERVER_NOT_RUNNING, AGENT_LIMIT_REACHED и подобные) описаны на страницах соответствующих разделов.

Авторизация и ключи

Причины и порядок действий по MISSING_API_KEY, INVALID_API_KEY и TOKEN_MISSING — Авторизация, ключи и права.

Состояние аккаунта Битрикс24

Состояние аккаунта, к которому привязан ключ, проверяется на каждом вызове. Отказы этой группы не привязаны к эндпоинту: пока аккаунт в одном из перечисленных состояний, ключ получает их на маршрутах /v1/..., у которых нет собственного отказа для этого состояния, и повтор запроса ничего не меняет.

Авторизация пользователей приложения (OAuth)

Отказ на приёме возврата может прийти не кодом, а параметром ?error= в адресе redirect_uri — token_exchange_failed, invalid_domain или profile_fetch_failed.

Полное описание потока — Авторизация пользователей приложения.

Права и скоупы

Причины и порядок действий по SCOPE_DENIED, BITRIX_ACCESS_DENIED и WRITE_BLOCKED_READONLY_KEY — Авторизация, ключи и права.

Валидация запроса

Пустое тело с заголовком Content-Type: application/json принимается как {} на маршрутах /v1/infra/*, а также на всех маршрутах пользовательских полей: /v1/userfields/:entity, /v1/userfields/:entity/types и /v1/userfields/:entity/:id, те же три пути под /v1/items/:entityTypeId/userfields, а также короткие адреса счетов /v1/userfields/invoices, /v1/userfields/invoices/types и /v1/userfields/invoices/:id. Операции, которым тело не нужно — POST /v1/infra/servers/:id/wake, DELETE /v1/infra/servers/:id/access-tokens/:tokenId и подобные, — отвечают по существу, а не отклоняют запрос на разборе тела. Так ведут себя клиенты, которые ставят этот заголовок на любой запрос (например, axios и PowerShell Invoke-RestMethod).

Дальше запрос проверяет сама операция, и код отказа зависит от маршрута — берите его из таблицы выше или со страницы нужной операции. Тело, которое не разбирается как JSON, на этих маршрутах отклоняется кодом INVALID_JSON_BODY, то есть пустое и битое тело различаются.

Причины и порядок действий по VALIDATION_ERROR, INVALID_PARAMS, MISSING_REQUIRED_FILTER и BATCH_LIMIT_EXCEEDED — Запрос и данные.

Размер тела запроса

Потолок зависит от маршрута. По умолчанию — 1 МБ. Создание и обновление записей, файлы ботов и чатов, note.file.add — 40 МиБ. Загрузка на Диск — 70 МБ. Файл внутри тела едет в base64 и растёт примерно на треть, поэтому исходный файл при потолке 40 МиБ — чуть меньше 30 МиБ. Тот же код приходит от пограничного слоя на его собственном пороге. Тело под необъявленным типом содержимого — например, text/plain — на маршрутах сущностей, пользовательских полей, чатов, заметок, ключей и Cowork/Code отклоняется кодом 415 FST_ERR_CTP_INVALID_MEDIA_TYPE, а пустое тело под тем же типом принимается там как {}. На /v1/infra/* и /v1/apps, включая публикацию исходников и места встраивания, потолок тела для непонятого типа равен одному байту, поэтому тот же запрос отвечает 413.

Крупным считается тело больше 1 МиБ — это тот же порог, что и потолок по умолчанию, — и суммарный объём одновременно обрабатываемых крупных тел ограничен. Отказ приходит там, где потолок тела поднят: записи сущностей, файлы ботов и файлы чатов, загрузка на Диск (POST /v1/files/upload), файлы заметок (POST /v1/note/documents/{documentId}/files), а также POST /v1/chat/completions и POST /v1/audio/transcriptions вместе со своими псевдонимами под /v1/ai/. Когда свободного объёма нет, приходит 429 LARGE_BODY_BACKEND_BUSY с заголовком Retry-After: 5. Так же отвечает запрос без заголовка Content-Length, если объём переваливает тот же порог уже по ходу передачи. Транскрипции — исключение: там учитывается только объявленный Content-Length, а загрузка без него ограничена одним потолком в 25 МБ на файл. На маршрутах AI у этого отказа конверт, совместимый с OpenAI: без поля success и с кодом large_body_backend_busy в нижнем регистре. Срок повтора берите из заголовка: поле error.retryAfter в теле этого отказа приходит не на всех путях.

Исключение — маршруты AI (/v1/ai/*, /v1/chat/*, /v1/audio/*, /v1/models): у них конверт ошибки, совместимый с OpenAI, и на превышении тела в error.code приходит служебный код фреймворка в нижнем регистре, а не PAYLOAD_TOO_LARGE.

Свой код и свой потолок у тела, которое несёт архив или файл внутри JSON: выкладка кода с source.content, загрузка файла с content и создание сервера с полем source принимают до 96 МБ тела, а сверх этого отвечают 413 INLINE_SOURCE_TOO_LARGE. Считается именно тело: содержимое едет в base64 и тяжелее исходных байт примерно на треть, поэтому потолку соответствует около 72 МБ самого архива. Решение принимается по заголовку Content-Length до чтения тела, а error.hint называет способ отправить тот же архив другим путём. Ссылка (source.url, url) и сохранённая версия (source.versionId) под этот потолок не попадают — у них свои 500 МБ.

Загрузка файлов

Предусловия подписок на события портала

Полное описание операций — Подписки на события портала.

Установка приложения через модуль-коннектор

Коды приходят на создании приложения там, где приложение устанавливает модуль-коннектор: на коробочном аккаунте, а на облачном — когда такой выпуск для аккаунта включён. При любом из этих отказов ни приложение, ни парный ключ не создаются.

Ресурс не найден

Доменные *_NOT_FOUND (BOT_NOT_FOUND, SERVER_NOT_FOUND, AGENT_NOT_FOUND, APP_NOT_FOUND, PORTAL_NOT_FOUND, USER_NOT_FOUND, FILE_NOT_FOUND, SUBSCRIPTION_NOT_FOUND) описаны на страницах соответствующих разделов.

B24_EMBEDDING_APP_NOT_FOUND (404) — отдельный случай: приложение есть на платформе Вайбкод, но Битрикс24 не знает его идентификатор. Условие и порядок восстановления — в группе «Права и скоупы» выше.

Два вида 404. Один и тот же HTTP-статус 404 означает два разных состояния — различайте их по error.code. ROUTE_NOT_FOUND — маршрута или глагола не существует, повторять запрос бессмысленно: проверьте путь по GET /v1/guide. ENTITY_NOT_FOUND и доменные коды вида *_NOT_FOUND — маршрут существует, не найден запрошенный объект. Оба состояния отвечают в едином конверте V1.

Маршрута не существует:

{
  "success": false,
  "error": {
    "code": "ROUTE_NOT_FOUND",
    "message": "Route GET:/v1/dealz not found. Check GET /v1/guide for available endpoints and verbs."
  }
}

Маршрут существует, объекта нет:

{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Элемент не найден"
  }
}

Имя метода Битрикс24 вместо пути V1. Пути API Вайбкод не повторяют имена методов Битрикс24, поэтому запрос вида GET /v1/crm.deal.list отвечает 404 ROUTE_NOT_FOUND и метод портала не вызывает. Для разобранных случаев ответ вдобавок называет верный маршрут в error.details.

Замена называется для четырёх методов: catalog.product.list → GET /v1/catalog-products, crm.deal.list → GET /v1/deals, crm.user.list → GET /v1/users, crm.deal.search → POST /v1/deals/search. На остальных путях приходит ROUTE_NOT_FOUND без details, и маршрут нужно найти через GET /v1/guide.

{
  "success": false,
  "error": {
    "code": "ROUTE_NOT_FOUND",
    "message": "Route GET:/v1/crm.deal.list not found. Bitrix24 method names are not V1 API paths; use GET /v1/deals instead. Check GET /v1/guide for required parameters and other endpoints.",
    "details": {
      "reason": "BITRIX_METHOD_AS_PATH",
      "bitrixMethod": "crm.deal.list",
      "suggestedEndpoint": { "method": "GET", "path": "/v1/deals" },
      "guide": { "method": "GET", "path": "/v1/guide" }
    }
  }
}

Повторите запрос по suggestedEndpoint, а состав параметров возьмите из guide: набор фильтров и полей у маршрута V1 свой, а не унаследованный от метода портала.

Причины и порядок действий по ENTITY_NOT_FOUND — Запрос и данные.

Конфликты состояния

Биллинг и тариф

Возникают на эндпоинтах создания и пробуждения инфраструктуры (серверы, агенты, управляемые боты). Ответ содержит userMessage на русском языке для показа в интерфейсе клиента.

Причины и порядок действий по BILLING_EXHAUSTED, COMMERCIAL_PLAN_REQUIRED, TRIAL_EXPIRED, B24_MARKET_SUBSCRIPTION_REQUIRED, B24_MARKET_TRIAL_USED и INT_TARIFF_REQUIRED — Биллинг, тариф и подписка.

Ограничение частоты

Причины и порядок действий по этой группе — Лимиты, очереди и паузы.

Бэкенд и сторонние сервисы

Причины и порядок действий по BITRIX_ERROR, METHOD_NOT_YET_AVAILABLE, BITRIX_UNAVAILABLE, BITRIX_TIMEOUT и INTERNAL_ERROR — Битрикс24 и платформа. По QUEUE_OVERFLOW и QUEUE_TIMEOUT — Лимиты, очереди и паузы.

Смотрите также

• Быстрый старт
• Ключи и авторизация
• Лимиты и оптимизация
• Batch
• CLI и cURL
• MCP для AI