Коды ошибок

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

Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key

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

• Авторизация, ключи и права — 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, B24_MARKET_SUBSCRIPTION_REQUIRED, B24_MARKET_TRIAL_USED, INT_TARIFF_REQUIRED
• Лимиты, очереди и паузы — RATE_LIMITED, CALLER_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
• Что безопасно повторять — дошёл ли целевой вызов до Битрикс24 и что делать с чтением или записью по каждому временному коду
• Повторы и обработка ошибок в коде — когда повторять запрос, а когда сначала перечитать сущность

Быстрый старт

Запросите сделку, которой нет на портале. Ответ придёт с HTTP-статусом 404 и кодом отказа в поле error.code:

curl "https://vibecode.bitrix24.tech/v1/deals/999999999" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Тот же конверт приходит на любом маршруте /v1/.... Поля конверта разобраны в разделе «Формат ответа при ошибке» ниже.

Полный пример

Клиент делает три запроса: читает список сделок, запрашивает несуществующую сделку и обращается по пути с опечаткой. Каждый отказ разбирается по error.code, а не по тексту error.message: язык сообщения заранее не известен. На RATE_LIMITED клиент ждёт столько секунд, сколько указано в заголовке Retry-After, и повторяет запрос не больше двух раз.

const BASE = 'https://vibecode.bitrix24.tech/v1'
const API_KEY = 'YOUR_API_KEY'

async function call(path, attempt = 1) {
  const res = await fetch(`${BASE}${path}`, { headers: { 'X-Api-Key': API_KEY } })
  const body = await res.json()
  if (body.success) return body

  const { code, message } = body.error
  switch (code) {
    case 'ENTITY_NOT_FOUND':
      console.log(`${path}: записи нет — повтор не поможет`)
      return null
    case 'ROUTE_NOT_FOUND':
      console.log(`${path}: такого маршрута нет — сверьте путь с GET /v1/guide`)
      return null
    case 'SCOPE_DENIED':
      console.log(`${path}: ключу не хватает скоупа — ${body.error.userMessage ?? message}`)
      return null
    case 'RATE_LIMITED': {
      if (attempt >= 3) throw new Error(`${path}: лимит запросов не отпускает`)
      const wait = Number(res.headers.get('Retry-After') ?? 1)
      await new Promise((resolve) => setTimeout(resolve, wait * 1000))
      return call(path, attempt + 1)
    }
    default:
      throw new Error(`${res.status} ${code}: ${message}`)
  }
}

const list = await call('/deals?limit=1')
// call() возвращает null на разобранном отказе — он уже напечатан, печатать нечего
if (list) console.log('Первая сделка:', list.data[0]?.id)

await call('/deals/999999999')
await call('/dealz')

Вывод на тестовом портале:

Первая сделка: 575
/deals/999999999: записи нет — повтор не поможет
/dealz: такого маршрута нет — сверьте путь с GET /v1/guide

Повторять ли запись после временного отказа и как ограничить число повторов для разных кодов — готовые обработчики на JavaScript, Python и PHP на странице Повторы и обработка ошибок в коде.

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

Каждый ответ с ошибкой возвращается в едином виде. 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. Некоторые отказы передают срок только заголовком — в одиночном ответе опирайтесь на него. У подошибки внутри успешного пакетного ответа отдельного заголовка нет: если срок передан, берите его из retryAfter этой подошибки.

Коды ошибок

Таблица покрывает основные коды, которые встречаются на любом эндпоинте 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 МБ.

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

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

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

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

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

Модуль Битрикс24 недоступен на портале

Это состояние портала, а не ошибка запроса: пока модуль на портале недоступен, повтор вернёт тот же отказ. Выключенный модуль включает администратор портала.

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

Доменные *_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 на русском языке для показа в интерфейсе клиента.

Что закрывает заморозка счёта. Отказ 402 ACCOUNT_FROZEN приходит на вызовах, которые оплачиваются балансом Вайбкод: инфраструктура /v1/infra/..., хранилище /v1/storage/..., поиск и глубокий поиск, расход AI сверх месячной квоты тарифа портала, депо исходников приложения, вложения обращений и правка обращения, а также выписка проектного ключа, создание приложения и создание приложения из Cowork/Code, активация купона, сброс лимитов по праву акции и подключение демо Маркетплейса.

Вызовы, за которые баланс не платит, под заморозкой продолжают работать: обращения к своему Битрикс24 через маршруты сущностей и пакетный вызов, AI в пределах месячной квоты тарифа портала, оплаченный период подписки Cowork/Code, список моделей, самоописание GET /v1/me, справочник, спека GET /v1/openapi.json, переписка по обращениям — создание, список, чтение одного обращения и комментарий к нему — и отзыв своего ключа Cowork/Code.

У всех перечисленных семейств, кроме AI, отказ выносится до валидации запроса, поэтому 400 и 404 на закрытом заморозкой вызове не приходят. У AI-маршрутов решение принимает сам обработчик, уже разобрав параметры: запрос с неверным полем ответит 400 раньше, чем дойдёт до проверки заморозки.

Важно: сужение отказа раскатывается по порталам постепенно. Пока оно не дошло до вашего портала, заморозка отвечает 402 ACCOUNT_FROZEN почти на любой вызов V1, включая чтения по сущностям и пакетный вызов. Открытыми в этом состоянии остаются самоописание, справочник, спека, те же четыре вызова переписки по обращениям и отзыв своего ключа Cowork/Code.

Причины и порядок действий по BILLING_EXHAUSTED, COMMERCIAL_PLAN_REQUIRED, 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