# Request and data

A detailed breakdown of the codes the Vibecode API returns for a malformed request body, a missing filter, and a call to a record that does not exist.

The summary table of all Vibecode API codes — [Error codes](/docs/errors).

## `VALIDATION_ERROR` (400)

The body or query parameters failed schema validation. Most V1 endpoints handle this through Zod, so the message names the specific fields that failed validation.

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

**Causes:**
- Required fields are missing.
- The value type does not match the schema (a string instead of a number, a wrong date format).
- The `Content-Type: application/json` header is missing. A body that does not parse as JSON is rejected with separate codes — `INVALID_JSON_BODY`, `FST_ERR_CTP_INVALID_JSON_BODY`, or `fst_err_ctp_invalid_json_body` on AI Router routes. Which one arrives depends on the route — see the [summary table of codes](/docs/errors).

**Solution:**
- Check the request body against the endpoint schema in the [API overview](/docs/entity-api) or on the specific endpoint page.
- Pass numbers without quotes and dates in ISO 8601 format (`2026-04-29T10:00:00`).
- Add the `Content-Type: application/json` header.

---

## `INVALID_PARAMS` (400)

Bitrix24 or the route handler found an invalid parameter value. Bitrix24 errors of the form `INVALID_PARAMS: ...` arrive under this same code.

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

**Causes:**
- An invalid path parameter value (for example, a non-number where a number is expected).
- Bitrix24 rejected a request parameter (for example, an unsupported value of an enum field).
- A write puts an object or an array into a field declared scalar (`string`, `number`, `boolean`, `date`, `datetime`). Bitrix24 stores such a value as the string `Array`, losing the data without an error, so the request is refused before the call. The check runs on entity create and update under `/v1/<entity>`, on both batch write surfaces and on import.
- An employee update puts an empty or whitespace-only string into `personalPhoto`. Bitrix24 treats it as a command to remove the current photo, so Vibecode refuses the value before the call. To keep the photo, omit the field.

**Boundaries of the value checks:**
- A name absent from the entity schema (custom fields `UF_*`, `propertyNNN`, a typo) is not checked — it has no declared type.
- A number or a boolean in a string field is accepted: Bitrix24 stores `123456` and `1`, and nothing is lost. The shape check accepts `null` too. The narrow exception is `users.personalPhoto` on UPDATE in `POST /v1/batch`: the global batch encoder would turn `null` into an empty command, so the sub-call is refused with `INVALID_PARAMS`. The previous `null` behaviour stays unchanged on the single PATCH and in the per-entity batch.
- Fields declared `object`, `array` or multi-value take structures as before.
- One deliberate exception is the file field: `users.personalPhoto` accepts, on write, an array of exactly two non-empty strings `[file name, base64]`, and only on the single-route `POST /v1/users` and `PATCH /v1/users/:id`. Any other structure in it — including the nested `{fileData: [...]}`, which Bitrix24 accepts with success while CLEARING the photo — and the same shape on batch routes are refused: a batch sub-call travels as a query string under the global body cap, and past its length limit the value would be truncated while still answering success. On UPDATE through the single PATCH or either batch route, an empty or whitespace-only string is also refused with `INVALID_PARAMS`; to keep the photo, omit the field. On CREATE in `POST /v1/users`, an empty string does not get the new refusal. Details: [Update an employee](/docs/entities/users/update). The `POST /v1/users/invite` wrapper accepts the same inline pair, translates the field name, and validates it separately with its own `PERSONAL_PHOTO_INVALID` code, but its body limit is still the GLOBAL one (1 MiB against the 40 MiB of the single routes), so an ordinary phone snapshot hits the size cap there: for a real photo use `POST /v1/users` or `PATCH /v1/users/:id`.
- The refusal shape differs by surface, and so does its reach. The [global batch](/docs/batch) refuses ONLY its own sub-call: the failure arrives in `data.errors["<call id>"]` with separate `code` and `message` fields, and neighbouring sub-calls still run. If every sub-call is refused before dispatch, the overall response remains `400 INVALID_REQUEST`. The per-entity batch write (`POST /v1/{entity}/batch`) and import refuse the WHOLE request: a `400` arrives with code `BATCH_ITEM_VALIDATION` or `IMPORT_ITEM_VALIDATION`, while the element index and `INVALID_PARAMS` live inside `message`, shaped `Item at index N: INVALID_PARAMS — …`. Such a response carries neither `data` nor per-item `results`, and nothing reaches Bitrix24: the check runs before the dispatch.
- A few bespoke write routes are not covered yet: `POST /v1/addresses`, `PATCH /v1/addresses`, task comments (`/v1/tasks/:taskId/comments`), `POST /v1/doc-templates`, Open Channels config and product rows (`/v1/{entity}/:id/products`). There the previous behaviour still applies.

**Solution:**
- Check the endpoint page for the values allowed for each parameter.
- For `filter`, use the field list from `GET /v1/<entity>/fields`.

---

## `MISSING_REQUIRED_FILTER` (400)

A required filter was not passed on a list endpoint that needs context.

```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]=..."
  }
}
```

**Causes:**
- The timeline record list requires the pair of parent identifiers `entityType` + `entityId`.
- The catalog product and section lists require `iblockId`, and the value list of a list property requires `propertyId`.
- [Activity aggregation](/docs/entities/activities/aggregate) requires a narrowing filter: the pair `ownerTypeId` + `ownerId`, or `responsibleId`, or a date bound on `createdAt` / `updatedAt` / `deadline`. Here the requirement is not "all of the above" but "any one of them" — Bitrix24 cannot count every activity of the account within the time allotted to the call. The platform enables the requirement per account. Check the state in `data.aggregateFilterRequirement.enforcement` in the `GET /v1/activities/fields` response.

The check runs before the call to Bitrix24 and applies to `GET /v1/{entity}`, `POST /v1/{entity}/search`, and `POST /v1/{entity}/aggregate`.

**Solution:**
- Add the required filter parameters listed in `message` or on the endpoint page.

---

## `BATCH_LIMIT_EXCEEDED` (400)

The request exceeds the item limit of a bulk operation. At the `/v1/batch` level the limit is reported through `INVALID_REQUEST` referencing `Array must contain at most 50 element(s)`. On domain endpoints for bulk operations (for example, `chats`, `task-comments`) there is a separate code, `BATCH_LIMIT_EXCEEDED`.

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

**Causes:**
- The array holds more than 50 items.

**Solution:**
- Split the operation into several requests of 50 items each.
- Use [batch requests](/docs/batch) for sequential calls with a single key.

---

## `ENTITY_NOT_FOUND` (404)

The CRM entity record with the given `id` does not exist or has been deleted.

```json
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Item not found"
  }
}
```

**Causes:**
- A record with this `id` really does not exist.
- The record was deleted by a parallel process.
- The entity was mixed up: the request goes to `/v1/deals/:id` while the ID belongs to a lead.

**Solution:**
- Check that the record exists through the entity's list endpoint.
- Restore it from the Bitrix24 recycle bin (through the account interface) if the record was deleted recently.

## See also

- [Error codes](/docs/errors)
- [API overview](/docs/entity-api)
- [Filtering syntax](/docs/filtering)
- [Batch](/docs/batch)
- [Retries and error handling in code](/docs/errors/handling)