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

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

Сводная таблица всех кодов API Вайбкод — [Коды ошибок](/docs/errors).

## `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. Какой из них придёт, зависит от маршрута — см. [сводную таблицу кодов](/docs/errors).

**Решение:**
- Сверить тело запроса со схемой эндпоинта в [обзоре API](/docs/entity-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 принимает успехом и при этом снимает фотографию) и та же форма на пакетных маршрутах отклоняются: подзапрос пакета едет строкой запроса под общим потолком тела, и за пределом длины значение обрезалось бы, отвечая при этом успехом. Подробности — [Обновить сотрудника](/docs/entities/users/update). Обёртка `POST /v1/users/invite` эту же форму принимает — она переводит имя поля и отдельно проверяет пару, — но потолок тела у неё остался ОБЩИМ (1 МиБ против 40 МиБ у одиночных), поэтому снимок с телефона там упрётся в размер: для настоящей фотографии берите `POST /v1/users` или `PATCH /v1/users/:id`.
- Форма отказа различается по поверхности, и различаются не только поля, но и охват. [Общий пакетный вызов](/docs/batch) отклоняет ТОЛЬКО свой подвызов: отказ приходит в `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`.
- [Агрегация дел](/docs/entities/activities/aggregate) требует сужающего фильтра: пара `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-запросы](/docs/batch) для последовательных вызовов с одного ключа.

---

## `ENTITY_NOT_FOUND` (404)

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

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

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

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

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

- [Коды ошибок](/docs/errors)
- [Обзор API](/docs/entity-api)
- [Синтаксис фильтрации](/docs/filtering)
- [Batch](/docs/batch)
- [Повторы и обработка ошибок в коде](/docs/errors/handling)