Для AI-агентов: markdown этой страницы — /docs-content/errors/request.md индекс документации — /llms.txt

Запрос и данные

Подробный разбор кодов, которыми API Вайбкод отвечает на некорректное тело запроса, недостающий фильтр и обращение к несуществующей записи.

Сводная таблица всех кодов API Вайбкод — Коды ошибок.

`VALIDATION_ERROR` (400)

Тело или query-параметры не прошли проверку схемы. Для большинства V1-эндпоинтов обработка реализована через Zod, поэтому сообщение содержит конкретные поля с проблемами.

JSON 
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "fields.title: Required; fields.stageId: Expected string, received number"
  }
}

Причины:

  • Отсутствуют обязательные поля.
  • Тип значения не соответствует схеме (строка вместо числа, неверный формат даты).
  • Отсутствует заголовок Content-Type: application/json. Тело, которое не разбирается как JSON, отклоняется отдельными кодами — INVALID_JSON_BODY, FST_ERR_CTP_INVALID_JSON_BODY или fst_err_ctp_invalid_json_body на маршрутах AI Router. Какой из них придёт, зависит от маршрута — см. сводную таблицу кодов.

Решение:

  • Сверить тело запроса со схемой эндпоинта в обзоре API или на странице конкретного эндпоинта.
  • Числа передавать без кавычек, даты — в формате ISO 8601 (2026-04-29T10:00:00).
  • Добавить заголовок Content-Type: application/json.

`INVALID_PARAMS` (400)

Битрикс24 или обработчик маршрута нашёл некорректное значение параметра. Ошибки Битрикс24 формата INVALID_PARAMS: ... приходят под этим же кодом.

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Path parameter :id must be a positive integer"
  }
}

Причины:

  • Некорректное значение path-параметра (например, не число там, где ожидается число).
  • Битрикс24 отверг параметр запроса (например, неподходящее значение enum-поля).
  • В поле, объявленное скаляром (string, number, boolean, date, datetime), на записи передан объект или массив. Такое значение Битрикс24 сохраняет как строку Array, то есть данные теряются без ошибки, поэтому запрос отклоняется до вызова. Проверка работает на создании и обновлении сущностей по путям /v1/<entity>, на обеих поверхностях пакетной записи и на импорте.

Границы проверки формы значения:

  • Имя, которого нет в схеме сущности (пользовательские поля UF_*, propertyNNN, опечатка), не проверяется — у него нет объявленного типа.
  • Число и логическое значение в строковом поле принимаются: Битрикс24 сохраняет 123456 и 1, значение не теряется. null тоже принимается.
  • Поля, объявленные как object, array и многозначные, структуру принимают штатно.
  • Отдельное исключение — поле-файл: users.personalPhoto принимает на записи массив ровно из двух непустых строк [имя файла, base64], и только на одиночных POST /v1/users и PATCH /v1/users/:id. Любая другая структура в нём (в том числе вложенная {fileData: [...]}, которую Битрикс24 принимает успехом и при этом снимает фотографию) и та же форма на пакетных маршрутах отклоняются: подзапрос пакета едет строкой запроса под общим потолком тела, и за пределом длины значение обрезалось бы, отвечая при этом успехом. Подробности — Обновить сотрудника. Обёртка POST /v1/users/invite эту же форму принимает — она переводит имя поля и отдельно проверяет пару, — но потолок тела у неё остался ОБЩИМ (1 МиБ против 40 МиБ у одиночных), поэтому снимок с телефона там упрётся в размер: для настоящей фотографии берите POST /v1/users или PATCH /v1/users/:id.
  • Форма отказа различается по поверхности, и различаются не только поля, но и охват. Общий пакетный вызов отклоняет ТОЛЬКО свой подвызов: отказ приходит в data.errors["<id вызова>"] отдельными полями code и message, соседние подвызовы выполняются. Пакетная запись по одной сущности (POST /v1/{entity}/batch) и импорт отклоняют ВЕСЬ запрос: приходит 400 с кодом BATCH_ITEM_VALIDATION или IMPORT_ITEM_VALIDATION, а номер элемента и INVALID_PARAMS — внутри message вида Item at index N: INVALID_PARAMS — …. Ни data, ни поэлементных results в таком ответе нет, и в Битрикс24 не уходит ни одной записи: проверка идёт до отправки.
  • Отдельные обособленные маршруты записи проверку пока не проходят: POST /v1/addresses, PATCH /v1/addresses, комментарии задач (/v1/tasks/:taskId/comments), POST /v1/doc-templates, настройки открытых линий и товарные строки (/v1/{сущность}/:id/products). Там прежнее поведение сохраняется.

Решение:

  • Проверить страницу эндпоинта: какие значения допустимы для каждого параметра.
  • Для filter использовать список полей из GET /v1/<entity>/fields.

`MISSING_REQUIRED_FILTER` (400)

Не передан обязательный фильтр на list-эндпоинте, который требует контекста.

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FILTER",
    "message": "GET /v1/timelines requires filter fields: entityType, entityId. Example: GET /v1/timelines?filter[entityType]=...&filter[entityId]=..."
  }
}

Причины:

  • Список записей таймлайна требует пары родительских идентификаторов entityType + entityId.
  • Список товаров и разделов каталога требует iblockId, а список значений списочного свойства — propertyId.
  • Агрегация дел требует сужающего фильтра: пара ownerTypeId + ownerId, либо responsibleId, либо граница по дате на createdAt / updatedAt / deadline. Здесь требование не «все перечисленные», а «любое одно» — Битрикс24 не успевает посчитать все дела аккаунта за отведённое на вызов время. Требование включается платформой отдельно на каждый аккаунт. Проверить состояние — data.aggregateFilterRequirement.enforcement в ответе GET /v1/activities/fields.

Проверка выполняется до обращения к Битрикс24 и действует на GET /v1/{entity}, POST /v1/{entity}/search и POST /v1/{entity}/aggregate.

Решение:

  • Добавить обязательные параметры фильтра, перечисленные в message или на странице эндпоинта.

`BATCH_LIMIT_EXCEEDED` (400)

Запрос превышает лимит элементов в массивной операции. На уровне /v1/batch лимит проверяется через INVALID_REQUEST со ссылкой на Array must contain at most 50 element(s). На доменных эндпоинтах массовых операций (например, chats, task-comments) — отдельный код BATCH_LIMIT_EXCEEDED.

JSON 
{
  "success": false,
  "error": {
    "code": "BATCH_LIMIT_EXCEEDED",
    "message": "Maximum 50 dialogs per bulk request (Bitrix24 batch limit)."
  }
}

Причины:

  • В массиве больше 50 элементов.

Решение:

  • Разделить операцию на несколько запросов по 50 элементов.
  • Использовать batch-запросы для последовательных вызовов с одного ключа.

`ENTITY_NOT_FOUND` (404)

Запись CRM-сущности с указанным id не существует или была удалена.

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

Причины:

  • Запись с таким id действительно не существует.
  • Запись была удалена параллельным процессом.
  • Перепутана сущность: запрос идёт на /v1/deals/:id, а ID — от лида.

Решение:

  • Проверить наличие записи через list-эндпоинт сущности.
  • Восстановить из корзины Битрикс24, если запись была удалена недавно (через интерфейс портала).

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