Error codes

Vibecode API error code reference: the unified response format, the code list, common causes, and how to fix them. Applies to all /v1/... endpoints.

Documentation sections

• Authorization, keys and permissions — MISSING_API_KEY, INVALID_API_KEY, TOKEN_MISSING, SCOPE_DENIED, BITRIX_ACCESS_DENIED, WRITE_BLOCKED_READONLY_KEY
• Request and data — VALIDATION_ERROR, INVALID_PARAMS, MISSING_REQUIRED_FILTER, BATCH_LIMIT_EXCEEDED, ENTITY_NOT_FOUND
• Billing and plans — BILLING_EXHAUSTED, COMMERCIAL_PLAN_REQUIRED, INT_TARIFF_REQUIRED
• Limits, queues, and pauses — RATE_LIMITED, CALLER_RATE_LIMITED, ERROR_LOOP_DETECTED, QUEUE_OVERFLOW, QUEUE_TIMEOUT, TIMEOUT_QUARANTINE, OPERATION_TIME_LIMIT
• Bitrix24 and the platform — BITRIX_ERROR, METHOD_NOT_YET_AVAILABLE, BITRIX_UNAVAILABLE, BITRIX_TIMEOUT, INTERNAL_ERROR
• What is safe to retry — whether the target call reached Bitrix24 and what to do with a read or write for each temporary code
• Retries and error handling in code — when to retry a request, and when to re-read the entity first

Error response format

Every error response is returned in a unified shape. error is an object.

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

Example response with an extra hint field (429 RATE_LIMITED) — here the retry delay arrives in the Retry-After: 2 header only:

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "QUERY_LIMIT_EXCEEDED",
    "hint": "Wait 1-2 seconds and retry. Use POST /v1/batch to combine up to 50 calls in 1 request."
  }
}

In a standalone HTTP response, the Retry-After header mirrors error.retryAfter when that field is present, for compatibility with the HTTP standard. Some refusals carry the delay only in the header, so use the header for a standalone response. A suberror inside a successful batch response has no separate header: if a delay is supplied, take it from that suberror's retryAfter field.

Code summary table

The table covers the core codes that appear on any Vibecode API endpoint. Domain codes (BOT_NOT_FOUND, SERVER_NOT_RUNNING, AGENT_LIMIT_REACHED, and similar) are documented on the pages of their respective sections.

Authorization and keys

Causes and step-by-step fixes for MISSING_API_KEY, INVALID_API_KEY and TOKEN_MISSING — Authorization, keys and permissions.

Bitrix24 account state

The state of the account a key is bound to is checked on every call. These refusals are not tied to an endpoint: while the account stays in one of the states below, the key receives them on every /v1/... route that has no refusal of its own for that state, and retrying changes nothing.

Application user authorization (OAuth)

A rejection at the callback step may arrive not as a code but as an ?error= parameter appended to the redirect_uri — token_exchange_failed, invalid_domain or profile_fetch_failed.

Full description of the flow — Application user authorization.

Permissions and scopes

Causes and step-by-step fixes for SCOPE_DENIED, BITRIX_ACCESS_DENIED and WRITE_BLOCKED_READONLY_KEY — Authorization, keys and permissions.

Request validation

An empty body sent with the Content-Type: application/json header is accepted as {} on the /v1/infra/* routes, and also on every custom-field route: /v1/userfields/:entity, /v1/userfields/:entity/types and /v1/userfields/:entity/:id, the same three paths under /v1/items/:entityTypeId/userfields, plus the short invoice paths /v1/userfields/invoices, /v1/userfields/invoices/types and /v1/userfields/invoices/:id. Operations that need no body — POST /v1/infra/servers/:id/wake, DELETE /v1/infra/servers/:id/access-tokens/:tokenId and the like — process the request normally instead of rejecting it while parsing the body. This accommodates clients that attach this header to every request (axios and PowerShell Invoke-RestMethod, for example).

The operation itself validates the request next, and the refusal code depends on the route — take it from the table above or from the page of the operation you call. A body that does not parse as JSON is rejected on these routes with INVALID_JSON_BODY, so an empty body and a malformed one are distinct cases.

Causes and step-by-step fixes for VALIDATION_ERROR, INVALID_PARAMS, MISSING_REQUIRED_FILTER and BATCH_LIMIT_EXCEEDED — Request and data.

Request body size

The limit depends on the route: 1 MB by default; record and list element creation and updates, bot and chat files, note.file.add — 40 MiB; upload to Drive — 70 MB. A file inside the body travels as base64 and grows by about a third, so with a 40 MiB limit the original file is just under 30 MiB. The same code arrives from the edge layer at its own threshold. A body sent under an undeclared content type — text/plain, for example — is refused with 415 FST_ERR_CTP_INVALID_MEDIA_TYPE on the entity, custom-field, chat, note, key and Cowork/Code routes, while an empty body under that same type is accepted there as {}. On /v1/infra/* and /v1/apps, including source publishing and placements, the body limit for an unrecognized type is one byte, so the same request answers 413.

A body above 1 MiB counts as large — the same threshold as the default limit — and the total volume of large bodies handled at a time is capped. The refusal occurs where the body limit is raised: entity records, list element writes, bot files and chat files, uploads to Drive (POST /v1/files/upload), note files (POST /v1/note/documents/{documentId}/files), and also POST /v1/chat/completions and POST /v1/audio/transcriptions together with their aliases under /v1/ai/. When that capacity is exhausted, 429 LARGE_BODY_BACKEND_BUSY arrives with a Retry-After: 5 header. A request without a Content-Length header gets the same answer once its volume crosses that threshold mid-transfer. Transcriptions are the exception: only a declared Content-Length counts there, and an upload without one is bounded by the single 25 MB per-file ceiling. On AI routes this refusal uses the OpenAI-compatible envelope: no success field, and the large_body_backend_busy code in lowercase. Take the retry delay from the header: the error.retryAfter field is not always present in the body.

AI routes are the exception (/v1/ai/*, /v1/chat/*, /v1/audio/*, /v1/models): they use an OpenAI-compatible error envelope, and on an oversize body error.code carries the framework's internal code in lowercase rather than PAYLOAD_TOO_LARGE.

A body that carries an archive or a file inside JSON has its own code and its own ceiling: code deploy with source.content, file upload with content and server creation with the source field accept up to 96 MB of body and answer 413 INLINE_SOURCE_TOO_LARGE above that. What is counted is the body itself: the content travels as base64 and runs roughly a third larger than the raw bytes, so the cap corresponds to about 72 MB of the archive. The decision is based on the Content-Length header before the body is read, and error.hint names a way to send the same archive through another path. A link (source.url, url) and a saved version (source.versionId) do not fall under this cap — they have their own 500 MB cap.

File uploads

Bitrix24 event subscription preconditions

Full description of the operations — Bitrix24 event subscriptions.

Application install through the connector module

The codes arrive on application creation where the application is installed by the connector module: on a self-hosted account, and on a cloud account once that issuance path is enabled for it. On any of these refusals neither the application nor the paired key is created.

Bitrix24 module unavailable on the account

This is a state of the Bitrix24 account, not a request error: while the module is unavailable on the account, a retry returns the same refusal. A Bitrix24 account administrator can enable a switched-off module.

Resource not found

Domain *_NOT_FOUND codes (BOT_NOT_FOUND, SERVER_NOT_FOUND, AGENT_NOT_FOUND, APP_NOT_FOUND, PORTAL_NOT_FOUND, USER_NOT_FOUND, FILE_NOT_FOUND, SUBSCRIPTION_NOT_FOUND) are documented on the pages of their respective sections.

B24_EMBEDDING_APP_NOT_FOUND (404) is a separate case: the application exists in Vibecode, but Bitrix24 does not know its identifier. The condition and the recovery steps are in the "Permissions and scopes" group above.

Two kinds of 404. The same HTTP status 404 covers two different states — tell them apart by error.code. ROUTE_NOT_FOUND — the route or verb does not exist, retrying is pointless: check the path against GET /v1/guide. ENTITY_NOT_FOUND and the domain *_NOT_FOUND codes — the route exists and the requested object is not found. Both states use the unified V1 envelope.

The route does not exist:

{
  "success": false,
  "error": {
    "code": "ROUTE_NOT_FOUND",
    "message": "Route GET:/v1/dealz not found. Check GET /v1/guide for available endpoints and verbs."
  }
}

The route exists, the object does not:

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

A Bitrix24 method name instead of a V1 path. Vibecode API paths do not mirror Bitrix24 method names, so a request such as GET /v1/crm.deal.list answers 404 ROUTE_NOT_FOUND and does not call the Bitrix24 method. For the cases that have been mapped, the response additionally names the right route in error.details.

A replacement is named for four methods: catalog.product.list → GET /v1/catalog-products, crm.deal.list → GET /v1/deals, crm.user.list → GET /v1/users, crm.deal.search → POST /v1/deals/search. On any other path ROUTE_NOT_FOUND arrives without details, and the route has to be found through GET /v1/guide.

{
  "success": false,
  "error": {
    "code": "ROUTE_NOT_FOUND",
    "message": "Route GET:/v1/crm.deal.list not found. Bitrix24 method names are not V1 API paths; use GET /v1/deals instead. Check GET /v1/guide for required parameters and other endpoints.",
    "details": {
      "reason": "BITRIX_METHOD_AS_PATH",
      "bitrixMethod": "crm.deal.list",
      "suggestedEndpoint": { "method": "GET", "path": "/v1/deals" },
      "guide": { "method": "GET", "path": "/v1/guide" }
    }
  }
}

Repeat the request against suggestedEndpoint and take the parameter set from guide: a V1 route has its own filters and fields rather than the ones inherited from the Bitrix24 method.

Causes and step-by-step fixes for ENTITY_NOT_FOUND — Request and data.

State conflicts

Billing and plans

These errors occur on endpoints that create and wake infrastructure (servers, agents, managed bots). The response includes a localized userMessage for display in the client interface.

What the account freeze closes. The 402 ACCOUNT_FROZEN refusal arrives on calls paid for from the Vibe credits balance: infrastructure /v1/infra/..., storage /v1/storage/..., search and deep research, AI spend beyond the Bitrix24 account plan's monthly quota, the application's source storage, ticket attachments and updating a ticket, and also issuing a project deployment key, creating an application and creating an application from Cowork/Code, redeeming a coupon, resetting limits with a promotion right and starting the Marketplace trial.

Calls that the balance does not pay for keep working under the freeze: requests to your own Bitrix24 through the entity routes and the batch call, AI within the Bitrix24 account plan's monthly quota, the paid period of a Cowork/Code subscription, the model list, the self-description GET /v1/me, the reference, the spec GET /v1/openapi.json, the support conversation — filing a ticket, listing tickets, reading one ticket and commenting on it — and the revocation of your own Cowork/Code key.

For every family listed above except AI, the refusal precedes request validation, so a call closed by the freeze returns neither 400 nor 404. On the AI routes the handler itself makes the decision after parsing the parameters, so a request carrying a bad field returns 400 before the freeze check is reached.

Important: the narrowed refusal is being rolled out account by account. Until it reaches your Bitrix24 account, the freeze answers 402 ACCOUNT_FROZEN on almost any V1 call, including entity reads and the batch call. What stays open in that state is the self-description, the reference, the spec, the same four support-conversation calls, and the revocation of your own Cowork/Code key.

Causes and step-by-step fixes for BILLING_EXHAUSTED, COMMERCIAL_PLAN_REQUIRED and INT_TARIFF_REQUIRED — Billing and plans.

Rate limiting

Causes and step-by-step fixes for this group — Limits, queues, and pauses.

Backend and third-party services

Causes and step-by-step fixes for BITRIX_ERROR, METHOD_NOT_YET_AVAILABLE, BITRIX_UNAVAILABLE, BITRIX_TIMEOUT and INTERNAL_ERROR — Bitrix24 and the platform. For QUEUE_OVERFLOW and QUEUE_TIMEOUT — Limits, queues, and pauses. Target-call delivery and retry safety for reads and writes are collected separately on What is safe to retry.

See also

• Quickstart
• Keys and authorization
• Limits and optimization
• What is safe to retry
• Batch
• CLI and cURL
• MCP for AI