Для 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.

`NESTED_FIELDS_ENVELOPE` (400)

Тело POST или PATCH содержит объект под собственным ключом fields, схема сущности не объявляет fields, а маршрут сам оборачивает карту полей. Этот вызов отклоняется до записи. Передавайте поля сущности в корне JSON. Отказ также срабатывает для пустого fields: {} и тела, где fields сочетается с плоскими полями. Неизвестные скалярные поля сохраняют прежнее поведение. Глобальный batch ставит NESTED_FIELDS_ENVELOPE в код ошибки вызова, при этом другие допустимые вызовы пакета могут выполниться. Импорт и пакетный маршрут сущности возвращают соответственно IMPORT_ITEM_VALIDATION и BATCH_ITEM_VALIDATION, а NESTED_FIELDS_ENVELOPE указывают в сообщении с индексом элемента.

`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.

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

  • Имя, которого нет в схеме сущности, проверяется по тому, что о нём сообщает сам Битрикс24 в своём списке полей (GET /v1/<entity>/fields показывает тот же список). Это поля, которые сущность отдаёт при чтении, но не объявляет, — например utmSource и locationId у сделок, birthdate, honorific и categoryId у контактов, employees у компаний, — и пользовательские поля UF_*. Правила те же, что у объявленных полей, с двумя отличиями ниже, и код тот же INVALID_PARAMS: объект или массив в поле, которое портал объявляет строковым (string, text, crm_status, crm_currency, location, url), числовым (integer, double, crm_category, user, employee, crm_contact, crm_company, crm_lead, crm_deal), логическим (boolean, char) или датным (date, datetime), отклоняется; нечисловая строка в числовом — тоже. В логическом поле портала проверяется только форма: такое значение уходит в Битрикс24 без преобразования, поэтому строковые формы вроде "yes" здесь не обещаются — передавайте Y/N. Пустая строка (ровно "") в поле-ссылке (user, employee, crm_contact, crm_company, crm_lead, crm_deal) и в пользовательском числовом поле (UF_*) не отклоняется — так Битрикс24 снимает привязку и очищает значение; в системном числовом поле и в категории (crm_category) она по-прежнему отклоняется: там она превращается в 0 — контакт с categoryId: "" переезжает в категорию 0. Без этой проверки Битрикс24 сохранял такую структуру строкой Array, нечисловую строку в categoryId — как 0, а объект там же — как 1 (контакт переезжал в другую категорию), и всё это с успешным ответом. Не проверяются: поля, которые портал объявляет многозначными или только для чтения; неизменяемые после создания (isImmutable) — на обновлении, где Битрикс24 их игнорирует (на создании и импорте они проверяются); поля типов вне перечисленных (файл, множественное поле контактов, перечисление, деньги); имена, которых в списке портала нет (опечатка остаётся в подсказке UNRECOGNIZED_WRITE_FIELD); сущности, чей список полей не сообщает признак многозначности (задачи). Список портала запрашивается только когда в теле есть такое имя, и держится в памяти пять минут; если Битрикс24 его не отдал, проверка молчит, значение уходит как прежде, и ближайшие тридцать секунд список перед записью не запрашивается повторно. Не покрыты: поля сотрудника (user.fields не сообщает типов), элементы списков, обёртка POST /v1/users/invite, товары каталога и сущности, у которых Битрикс24 не отдаёт живой список полей (заказы, оплаты, календарь, сайты, отделы, группы и другие — их GET /v1/<entity>/fields показывает только описание сущности).
  • Число и логическое значение в строковом поле принимаются: Битрикс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, если запись была удалена недавно (через интерфейс портала).

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