#Error codes

Reference of Vibe API error codes: the unified response format, the code list, common causes, and how to fix them. Applies to all /v1/... endpoints.

#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 extra fields (429 RATE_LIMITED):

{
  "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.",
    "retryAfter": 2
  }
}

The Retry-After HTTP header mirrors the error.retryAfter value for compatibility with the HTTP standard.

#Code summary table

The table covers the core codes that appear on any Vibe 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

#Application user authorization (OAuth)

A rejection on the return 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

#Request validation

#File uploads

#Portal event subscription preconditions

For the full operation reference, see portal event subscriptions.

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

#State conflicts

#Billing and plans

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

#Rate limiting

#Backend and third-party services

#Detailed reference

#`MISSING_API_KEY` (401)

The request does not contain the X-Api-Key header.

{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Pass via X-Api-Key header."
  }
}

Causes:

• The X-Api-Key or Authorization header was not passed.
• The header was passed with an empty value.

Fix:

• Add the X-Api-Key: vibe_api_... or X-Api-Key: vibe_app_... header.
• Verify that the environment variable holding the key is set correctly (for CLI tools and SDKs).

#`INVALID_API_KEY` (401)

The passed key does not exist or its format is unrecognized.

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}

Causes:

• A typo or extra whitespace in the key.
• The key was deleted by its owner or an administrator.
• The key is from a different environment (staging/production).
• The prefix is not among the supported ones: vibe_api_, vibe_app_, vibe_live_, vibe_mgmt_.

Fix:

• Check the key in your account on the /keys page.
• Create a new key if the old one was deleted.

#`SCOPE_DENIED` (403)

The key lacks the required scope for the requested operation.

{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope"
  }
}

Causes:

• CRM entities require the crm scope, tasks require task, the bot platform requires imbot, the AI Router requires vibe:ai, infrastructure requires vibe:infra.
• The key's scope was narrowed at creation time.

Fix:

• Open the key page in your account and issue a new key with a broader scope set.
• The full list of scopes and their purpose is on the Keys and authorization page.

#`BITRIX_ACCESS_DENIED` (403)

Bitrix24 returned ACCESS_DENIED: the user or app lacks permission for the entity or operation.

{
  "success": false,
  "error": {
    "code": "BITRIX_ACCESS_DENIED",
    "message": "ACCESS_DENIED"
  }
}

Causes:

• The user lacks permission for the entity in CRM (e.g. another user's deal with restricted visibility).
• The Bitrix24 app does not have the required scope in its permissions on the Bitrix24 account.
• The requested module is disabled in the Bitrix24 account (no CRM, no bot platform, and so on).

Fix:

• Check the user's permissions in the Bitrix24 entity card.
• Open the app settings in the Bitrix24 account and broaden the permission set.

#`WRITE_BLOCKED_READONLY_KEY` (403)

The key is in read-only mode (accessMode: "READONLY"), but the request performs a write. The full description of the mode, switching, and portal policy is in Access mode.

{
  "success": false,
  "error": {
    "code": "WRITE_BLOCKED_READONLY_KEY",
    "message": "Key is in read-only mode. Switch to read+write in /keys to enable writes.",
    "details": {
      "method": "crm.item.add",
      "keyName": "MCP key",
      "currentMode": "READONLY",
      "switchUrl": "/keys"
    }
  }
}

details fields:

Causes:

• An API key or authorization key (vibe_api_, vibe_app_) in READONLY mode made a call that proxies to Bitrix24 as a write operation: create, update, delete, an action on an entity.
• A management key (vibe_live_) in READONLY mode made a request with the POST, PATCH, PUT, or DELETE HTTP method — e.g. an attempt to create a key via POST /v1/keys or delete a feedback record.

Fix:

• The key owner should open API Keys, select "Read and write" under the Access mode block in the relevant key's card, and save. The mode applies to the next request, no reissue needed.
• If the toggle in the card is unavailable — the Bitrix24 account administrator restricted the mode. Ask the administrator to lift the restriction for this key.
• When working through an AI agent — the effective mode is returned by GET /v1/me in the data.accessMode field. If writes are needed permanently, issue a separate key in "read and write" mode.

#`VALIDATION_ERROR` (400)

The body or query parameters failed schema validation. Most V1 endpoints validate via Zod, so the message lists the specific problematic fields.

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

Causes:

• Required fields are missing.
• A value's type does not match the schema (string instead of number, wrong date format).
• The Content-Type: application/json header is missing. A body that cannot be parsed as JSON is rejected with separate codes — INVALID_JSON_BODY, FST_ERR_CTP_INVALID_JSON_BODY, or fst_err_ctp_invalid_json_body on the AI Router routes. Which one you get depends on the route — see the table above.

Fix:

• Check the body against the endpoint schema in the entity reference or on the specific endpoint page.
• Pass numbers without quotes, 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 (e.g. a non-number where a number is expected).
• Bitrix24 rejected a request parameter (e.g. an unsupported enum field value).

Fix:

• Check the endpoint page: which values are valid 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": "filter[entityType] and filter[entityId] are required for /v1/timelines"
  }
}

Causes:

• The list of timeline records, comments, and other "nested" data requires a pair of parent identifiers.

Fix:

• Add the required filter parameters listed in message or on the endpoint page.

#`BATCH_LIMIT_EXCEEDED` (400)

The request exceeds the element limit in a bulk operation. At the /v1/batch level the limit is checked via INVALID_REQUEST referencing Array must contain at most 50 element(s). On domain bulk endpoints (e.g. chats, task-comments) — a dedicated BATCH_LIMIT_EXCEEDED code.

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

Causes:

• The array has more than 50 elements.

Fix:

• Split the operation into several requests of 50 elements each.
• Use batch requests for sequential calls from a single key.

#`ENTITY_NOT_FOUND` (404)

A CRM entity record with the given id does not exist or was deleted.

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

Causes:

• A record with this id genuinely does not exist.
• The record was deleted by a concurrent process.
• The wrong entity: the request goes to /v1/deals/:id, but the ID is from a lead.

Fix:

• Check that the record exists via the entity's list endpoint.
• Restore it from the Bitrix24 recycle bin if it was deleted recently (via the Bitrix24 account interface).

#`RATE_LIMITED` (429)

Bitrix24 throttled the request rate or an internal Vibecode limit was triggered.

{
  "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.",
    "retryAfter": 2
  }
}

Response headers:

Retry-After: 2

Causes:

• Too many concurrent requests piled up from a single key: the general platform limit is counted per API key. The exceptions are POST /v1/search, POST /v1/research and POST /v1/batch, where the limit is counted per portal and all of its keys share one counter.
• The requests-per-second limit on the Bitrix24 side was exceeded. It is counted per portal.

Fix:

• Wait the number of seconds given in error.retryAfter or the Retry-After header.
• Implement retries with exponential backoff.
• Combine up to 50 calls via POST /v1/batch.
• Cache rarely changing reference data — fields, statuses, currencies.

#`ERROR_LOOP_DETECTED` (429)

Vibecode detects a series of identical errors on a single key for a single Bitrix24 method — and temporarily blocks the request on the Vibecode side to avoid inflating Bitrix24 counters. Every Nth request is forwarded onward: if the backend has recovered, the block is lifted automatically.

{
  "success": false,
  "error": {
    "code": "ERROR_LOOP_DETECTED",
    "message": "Vibe-side block (not a Bitrix24 limit). 12 failures on crm.deal.list in the last hour.",
    "hint": "Every 50th request will probe for recovery — keep retrying with backoff. If you suspect a platform-side issue (e.g. 5xx during an outage), platform admin can clear the block via POST /api/platform/analytics/circuit-breaker/<apiKeyId>/clear.",
    "retryAfter": 60
  }
}

Causes:

• A bug in the client code: a request with identical parameters repeats and consistently fails.
• A platform outage on the Bitrix24 side during the burst of requests.

Fix:

• Read message — it names the specific method with the error series.
• Find the request's source in the code, fix the parameters or logic.
• During a platform outage — the platform administrator can clear the block via POST /api/platform/analytics/circuit-breaker/<apiKeyId>/clear.

#`BILLING_EXHAUSTED` (402)

The billing account dropped into the red zone: the balance is negative, the grace period is exhausted. Requests to create and wake infrastructure are blocked until a top-up.

{
  "success": false,
  "error": {
    "code": "BILLING_EXHAUSTED",
    "message": "Account is frozen due to negative balance.",
    "userMessage": "The billing account is frozen due to a negative balance. Top up the account to continue working with servers and agents.",
    "hint": "Top up the account at /billing/topup, then call POST /v1/portals/:id/refresh-tariff."
  }
}

Causes:

• There are no funds on the balance to cover the hourly cost of servers and agents.

Fix:

• Top up the balance on the /billing/topup page.
• After topping up, call POST /v1/portals/:id/refresh-tariff to update the status.

#`COMMERCIAL_PLAN_REQUIRED` (402)

Creating servers and agents is unavailable on the free Bitrix24 plan after the trial period ends.

{
  "success": false,
  "error": {
    "code": "COMMERCIAL_PLAN_REQUIRED",
    "message": "Commercial Bitrix24 plan required for infrastructure operations.",
    "userMessage": "Infrastructure creation is available on commercial Bitrix24 plans. The trial period has already been used.",
    "hint": "Upgrade plan at https://www.bitrix24.com/prices/, then call POST /v1/portals/:id/refresh-tariff."
  }
}

Fix:

• Upgrade the Bitrix24 plan to a commercial one.
• After upgrading, call POST /v1/portals/:id/refresh-tariff or GET /v1/me?refresh=tariff.

#`TRIAL_EXPIRED` (402)

The trial period has ended and the plan is still free.

{
  "success": false,
  "error": {
    "code": "TRIAL_EXPIRED",
    "message": "Trial period has ended.",
    "userMessage": "The trial period has ended. Switch to a commercial Bitrix24 plan to keep using servers and agents."
  }
}

Fix:

• Switch to a commercial Bitrix24 plan.
• Update the status via POST /v1/portals/:id/refresh-tariff.

#`BITRIX_ERROR` (422)

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

{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Invalid filter: field 'NON_EXISTENT_FIELD' is not allowed in filter",
    "hint": "Known Bitrix24 limitation: …"
  }
}

Causes:

• Bitrix24 rejected the operation for a business reason: incompatible state, unsupported value, business rule.
• The request runs in 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.

#`BITRIX_UNAVAILABLE` (502)

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

{
  "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, implementing retries with exponential backoff.
• ⚠️ For write operations (POST/PATCH) — first check whether the original request applied. A slow portal may process the write AFTER the API already returned a timeout — a blind retry creates a duplicate (task, epic, comment). Before retrying, GET the list/record (e.g. search by the title you just sent) and retry only if the record is absent.
• Check the portal status at /bitrix/admin/site_checker.php (for the Bitrix24 account administrator).

#`QUEUE_OVERFLOW` (429)

The request queue to Bitrix24 for a specific portal is overflowing: too many calls are already pending (more than 100 by default). The response returns instantly, within milliseconds, with the HTTP header Retry-After: N (seconds).

{
  "success": false,
  "error": {
    "code": "QUEUE_OVERFLOW",
    "message": "Portal queue overloaded — 100 Bitrix24 calls already pending",
    "userMessage": "The portal queue is overflowing. Too many concurrent requests to Bitrix24.",
    "hint": "Honor the Retry-After header. Use exponential backoff with jitter for repeated failures.",
    "retryAfter": 10
  }
}

Fix:

• The portal queue is overflowing — retry after Retry-After seconds, using backoff with jitter (a random addition to the delay) so retries from different clients don't arrive as one wave.
• Reduce concurrency on the client side.
• Combine calls via POST /v1/batch.

#`QUEUE_TIMEOUT` (429)

The request queue to Bitrix24 for a specific portal is saturated: more than 30 seconds of waiting.

{
  "success": false,
  "error": {
    "code": "QUEUE_TIMEOUT",
    "message": "Portal queue saturated — too many concurrent Bitrix24 calls",
    "userMessage": "Requests to Bitrix24 have been queued for over 30 seconds. The portal likely has many concurrent operations.",
    "hint": "If this is a /search request with a wide date range, try adding \"autoWindow\": false OR narrow the date range to <14 days. See /v1/guide for optimization tips.",
    "retryAfter": 10
  }
}

The request was NOT sent to Bitrix24 — safe to retry.

Fix:

• Retry after retryAfter seconds, using backoff with jitter.
• Reduce concurrency.
• For /search endpoints — narrow the date range or pass autoWindow: false.
• Combine calls via POST /v1/batch.

#`BITRIX_TIMEOUT` (503)

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

{
  "success": false,
  "error": {
    "code": "BITRIX_TIMEOUT",
    "message": "Bitrix24 accepted the request but did not respond within 15s",
    "hint": "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 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's absent.

#`INTERNAL_ERROR` (500)

An unexpected error on the Vibe API side.

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

#Retries and backoff

Summary of codes that signal a temporary problem and imply a retry:

#Error handling in code

#JavaScript

async function vibeRequest(url, options = {}) {
  const response = await fetch(url, {
    ...options,
    headers: {
      'X-Api-Key': process.env.VIBE_API_KEY,
      'Content-Type': 'application/json',
      ...options.headers,
    },
  });

  const data = await response.json();

  if (!data.success) {
    const { code, message, retryAfter } = data.error;

    switch (code) {
      case 'RATE_LIMITED':
      case 'QUEUE_TIMEOUT': {
        const wait = retryAfter ?? Number(response.headers.get('Retry-After')) ?? 1;
        await new Promise(r => setTimeout(r, wait * 1000));
        return vibeRequest(url, options);
      }

      case 'BITRIX_UNAVAILABLE':
        await new Promise(r => setTimeout(r, 5000));
        return vibeRequest(url, options);

      case 'MISSING_API_KEY':
      case 'INVALID_API_KEY':
        throw new Error('Check the API key');

      default:
        throw new Error(`${code}: ${message}`);
    }
  }

  return data;
}

#Python

import os
import time
import requests

def vibe_request(url, method="GET", json_data=None):
    headers = {
        "X-Api-Key": os.environ["VIBE_API_KEY"],
        "Content-Type": "application/json",
    }

    response = requests.request(method, url, headers=headers, json=json_data)
    data = response.json()

    if not data.get("success"):
        err = data.get("error", {})
        code = err.get("code")
        message = err.get("message")
        retry_after = err.get("retryAfter") or int(response.headers.get("Retry-After", 1))

        if code in ("RATE_LIMITED", "QUEUE_TIMEOUT"):
            time.sleep(retry_after)
            return vibe_request(url, method, json_data)

        if code == "BITRIX_UNAVAILABLE":
            time.sleep(5)
            return vibe_request(url, method, json_data)

        raise Exception(f"{code}: {message}")

    return data

#PHP

function vibeRequest(string $url, string $method = 'GET', ?array $data = null): array {
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_HTTPHEADER => [
            'X-Api-Key: ' . getenv('VIBE_API_KEY'),
            'Content-Type: application/json',
        ],
    ]);
    if ($data !== null) {
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    }
    $body = json_decode(curl_exec($ch), true);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($body === null) {
        throw new Exception("HTTP error: $httpCode");
    }

    if (empty($body['success'])) {
        $errCode = $body['error']['code'] ?? 'UNKNOWN';
        $errMsg = $body['error']['message'] ?? 'Unknown error';
        $retryAfter = $body['error']['retryAfter'] ?? 1;

        if (in_array($errCode, ['RATE_LIMITED', 'QUEUE_TIMEOUT'], true)) {
            sleep((int) $retryAfter);
            return vibeRequest($url, $method, $data);
        }

        if ($errCode === 'BITRIX_UNAVAILABLE') {
            sleep(5);
            return vibeRequest($url, $method, $data);
        }

        throw new Exception("$errCode: $errMsg");
    }

    return $body;
}

#See also

• Quick Start — your first request in 2 minutes
• Keys and authorization — key types, format, scopes
• Optimization and batch — reducing call volume and avoiding RATE_LIMITED
• Batch requests — combining up to 50 calls into one request
• CLI and cURL — working via the command line
• MCP for AI — integration with AI tools