For AI agents: markdown of this page — /docs-content-en/errors/platform.md documentation index — /llms.txt

Bitrix24 and the platform

A detailed breakdown of the codes the Vibecode API returns when Bitrix24 rejects an operation or the failure happens on the platform itself.

A summary table of all Vibecode API codes — Error codes.

`BITRIX_ERROR` (422)

Bitrix24 returned a business error that does not fall under narrower categories (ACCESS_DENIED, NOT_FOUND, INVALID_PARAMS, RATE_LIMITED).

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "The requested period exceeds the maximum of 1 year",
    "b24Code": "PERIOD_TOO_LARGE"
  }
}

Causes:

  • Bitrix24 rejected the operation for a business reason: incompatible state, unsupported value, business rule.
  • The request runs against a Bitrix24 account where the corresponding module is disabled.

Fix:

  • Read message — it holds the original error text from Bitrix24.
  • If hint is present — use it as the first diagnostic step.
  • For programmatic handling, read the error.b24Code field — the machine-readable reason code from Bitrix24, for example BOT_TYPE_NOT_ALLOWED or PERIOD_TOO_LARGE. Branch in code on it, not on the message text. When Bitrix24 sends no separate code, the field is absent from the response — provide a default branch.

`METHOD_NOT_YET_AVAILABLE` (422)

The method ships in a Bitrix24 update that has not reached this portal yet. This is a rollout signal, not a call error: the same request starts working on its own once the update arrives. On some methods a separate permission check applies after that — the method page describes it.

JSON 
{
  "success": false,
  "error": {
    "code": "METHOD_NOT_YET_AVAILABLE",
    "message": "Method \"imopenlines.v2.Stat.get\" is rolling out in update imopenlines 26.700.0 and is not yet available on this portal — this is not a call error.",
    "release": "imopenlines 26.700.0"
  }
}

Fix:

  • Branch on error.code, not on the text of message.
  • The error.release field is the whole update identifier: the module name and the version number in one string. Compare it for equality as a string, do not parse it as a version number.
  • Frequent retries change nothing: the state flips when the update reaches the portal, not when the call is repeated. There is no Retry-After header and no retryAfter field in this refusal, because the platform does not know when the update will arrive. Until then, show the user that the named update is pending rather than an integration error.

`BITRIX_UNAVAILABLE` (502)

Bitrix24 returned 5xx or did not respond within the allotted time.

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_UNAVAILABLE",
    "message": "Bitrix24 returned 503 Service Unavailable"
  }
}

Causes:

  • Maintenance or overload on the Bitrix24 side.
  • Network problems between Vibecode and the Bitrix24 portal.

Fix:

  • Retry the request after a few minutes, using exponential backoff.
  • For write operations (POST/PATCH) — first check whether the original request was applied. A slow portal may process the write after the response has already been sent to the client, and a blind retry creates a duplicate. The check follows the same procedure as for BITRIX_TIMEOUT.

`BITRIX_TIMEOUT` (503)

Bitrix24 accepted the request but did not respond within 15 seconds — the outcome is unknown: the request MAY have been applied on the portal side.

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_TIMEOUT",
    "message": "Bitrix24 request timed out after 15s",
    "hint": "Bitrix24 accepted the request but did not respond within the configured time limit. For WRITE operations, verify whether the change was applied (re-read the entity) before retrying. Reads are safe to retry.",
    "retryAfter": 10
  }
}

Fix:

  • For reads (GET//search) — safe to retry, after a longer backoff than for 429.
  • For write operations (POST/PATCH) — re-read the entity first. The change may have already been applied on the Bitrix24 side even though no response arrived. A blind retry creates a duplicate (task, epic, comment). Check whether the record exists (e.g. search by the title you just sent) and retry the write only if it is absent.

`INTERNAL_ERROR` (500)

An unexpected error on the Vibecode API side.

JSON 
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  }
}

Fix:

  • Retry the request.
  • If the error reproduces consistently — submit a ticket via POST /v1/feedback with the request time. The X-Request-Id header from the response speeds up diagnosis.

See also