Для 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>, на обеих поверхностях пакетной записи и на импорте.
  • При обновлении сотрудника в personalPhoto передано значение, из которого Битрикс24 не может собрать файл: пустая строка, строка только из пробельных символов, литерал false, логические true и false, число 0, строка, в которой меньше двух символов алфавита base64, inline-пара [имя файла, base64], содержимое которой — одно из перечисленного, и любая другая структура, у которой второго значения нет, оно null или нечитаемо (вложенная {fileData: [...]}, пустой массив, массив из одного элемента, явный null или структура на месте содержимого). Каждое из них Битрикс24 воспринимает как команду снять текущую фотографию, поэтому Вайбкод отклоняет значение до вызова. Чтобы сохранить фотографию, не передавайте поле, а чтобы снять её — вызовите DELETE /v1/users/:id/personal-photo.

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

  • Имя, которого нет в схеме сущности (пользовательские поля UF_*, propertyNNN, опечатка), не проверяется — у него нет объявленного типа.
  • Число и логическое значение в строковом поле принимаются: Битрикс24 сохраняет 123456 и 1, значение не теряется. Проверка формы также принимает null. Исключение — users.personalPhoto на UPDATE: логические true и false, число 0 и остальные значения, из которых Битрикс24 не соберёт файл (пустая строка, строка только из пробельных символов, литерал false, строка, в которой меньше двух символов алфавита base64, и inline-пара с таким же содержимым), отклоняются с INVALID_PARAMS на всех трёх поверхностях обновления — на одиночном PATCH /v1/users/:id, в пакетной записи по одной сущности и в POST /v1/batch. Отдельно от них стоит null: он отклоняется только на UPDATE в POST /v1/batch, потому что кодировщик общего пакета превратил бы его в пустую команду. На одиночном PATCH и в пакетной записи по одной сущности null до ветки удаления не доходит и фотографию не снимает, поэтому там он не отклоняется.
  • Для остальных скалярных типов проверяется соответствие ЗНАЧЕНИЯ объявленному типу, а не только его форма. Числовое поле принимает JSON-число или числовую строку с точкой как разделителем дробной части ("1234.56"); ведущие и конечные пробелы вокруг такой строки игнорируются (" 1234.56 " принимается), а запятая ("1234,56" — конвенция ru/de/fr/es/it/br) — нет: значение отклоняется INVALID_PARAMS с явным указанием на точку, а не приводится к ней молча. Булево поле принимает JS true/false либо распознаваемые строковые формы без учёта регистра и с обрезкой пробелов ("true"/"false", "yes"/"no", "y"/"n", "1"/"0") — JSON-число 1 или 0 такой формой не считается и тоже отклоняется. Числовые поля tasks.priority и tasks.status дополнительно проверяются на принадлежность объявленному перечню значений — значение вне перечня отклоняется INVALID_PARAMS; у остальных enum-полей реестра перечень не закрытый, и такая проверка на них не выполняется. Пустая строка — исключение, которое работает ТОЛЬКО в строковом поле (см. выше): в числовом и булевом поле она не очищает значение, а отклоняется как несоответствие типа, потому что иначе Битрикс24 привёл бы её к 0 или к false под видом успеха. Поля, объявленные date и datetime, эту проверку значения пока не проходят: структурное значение (объект, массив) в них по-прежнему отклоняется (см. выше), а некорректная по формату строка — нет, она уходит в Битрикс24 как есть.
  • Строковое поле с объявленным ограничением длины (сегодня это только order-statuses.color, предел 10 символов) отклоняет INVALID_PARAMS значение длиннее предела вместо того, чтобы молча обрезать его до ширины колонки базы. У строкового поля без объявленного предела проверка длины не выполняется.
  • Поля, объявленные как object, array и многозначные, структуру принимают штатно.
  • Отдельное исключение — поле-файл: users.personalPhoto принимает на записи массив ровно из двух непустых строк [имя файла, base64], и только на одиночных POST /v1/users и PATCH /v1/users/:id. Любая другая структура в нём (в том числе вложенная {fileData: [...]}, которую Битрикс24 принимает успехом и при этом снимает фотографию) и та же форма на пакетных маршрутах отклоняются: подзапрос пакета едет строкой запроса под общим потолком тела, и за пределом длины значение обрезалось бы, отвечая при этом успехом. На UPDATE через одиночный PATCH или любой из двух пакетных маршрутов с INVALID_PARAMS отклоняется любое значение, из которого Битрикс24 не соберёт файл: пустая строка, строка только из пробельных символов, литерал false, логические true и false, число 0, строка, в которой меньше двух символов алфавита base64, и та же inline-пара, если её содержимое — одно из перечисленного (форма из двух непустых строк ничего не говорит о том, что содержимое декодируется). Чтобы сохранить фотографию, не передавайте поле, а чтобы снять её — вызовите DELETE /v1/users/:id/personal-photo. На CREATE в POST /v1/users пустая строка не получает новый отказ. Подробности — Обновить сотрудника. Обёртка POST /v1/users/invite принимает ту же inline-пару, переводит имя поля и проверяет её отдельно с собственным кодом PERSONAL_PHOTO_INVALID, но потолок тела у неё остался ОБЩИМ (1 МиБ против 40 МиБ у одиночных), поэтому снимок с телефона там упрётся в размер: для настоящей фотографии берите POST /v1/users или PATCH /v1/users/:id.
  • Форма отказа различается по поверхности, и различаются не только поля, но и охват. Общий пакетный вызов отклоняет ТОЛЬКО свой подвызов: отказ приходит в data.errors["<id вызова>"] отдельными полями code и message, соседние подвызовы выполняются. Если все подвызовы отклонены до отправки, общий ответ сохраняет 400 INVALID_REQUEST. Пакетная запись по одной сущности (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, если запись была удалена недавно (через интерфейс портала).

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