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.

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

{
  "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.

Solution:

• Check the request body against the endpoint schema in the API overview 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.

{
  "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. 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 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.

{
  "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 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.

{
  "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 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.

{
  "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
• API overview
• Filtering syntax
• Batch
• Retries and error handling in code