Authorization, keys and permissions

A detailed breakdown of the codes the Vibecode API returns when a key is not recognized, lacks the required permissions, or runs in read-only mode.

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

`MISSING_API_KEY` (401)

The request carries no 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 instead of production or the other way around.
• The prefix is not among the supported ones: vibe_api_, vibe_app_, vibe_live_.

Fix:

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

`TOKEN_MISSING` (401)

The key carries no Bitrix24 credentials, so there is no way to call Bitrix24. The cause depends on the key type — these are two different scenarios.

A personal key (vibe_api_*) reaches Bitrix24 through a webhook. When the key has no webhook, the response on entity calls (/v1/{entity} and POST /v1/batch) carries a machine-readable reason in error.details. Other routes return the same code without details:

{
  "success": false,
  "error": {
    "code": "TOKEN_MISSING",
    "message": "This personal API key (vibe_api_*) has no Bitrix24 webhook credentials, ...",
    "details": {
      "reason": "INT_TARIFF_REQUIRED",
      "paywallCode": "INT_TARIFF_REQUIRED"
    }
  }
}

Values of details.reason:

Reconnecting — POST /api/keys/:id/reconnect: issues a webhook for the key without changing the key string (no integration has to be reconfigured) and clears the auto-disable on linked bots. Not applicable to app keys, system-managed keys, or keys with no Bitrix24 scopes — those still need a new key.

⚠️ Reconnecting is NOT available for every key: the platform refuses it with 400 RECONNECT_NOT_APPLICABLE for app keys, keys with a system-managed purpose (including the Cowork key), keys linked to a server, to a live agent or to a live managed bot, and keys with no Bitrix24 scopes. For these keys the error message does not offer reconnecting at all — the cause has to be closed on the Bitrix24 account, and the platform then mints the webhook on its own.

paywallCode arrives only for the plan-related reason and repeats it. The upgradeUrl field — a link to the upgrade page in the Bitrix24 account — never comes with INT_TARIFF_REQUIRED.

The same condition also blocks app installation and placement binding — there it arrives as a standalone 403 code, covered in Billing and plans.

An app key (vibe_app_*) keeps the Bitrix24 tokens in a per-user session, not on the key. For a call with X-Api-Key alone and no Authorization: Bearer <session token>, TOKEN_MISSING is the correct answer — this branch carries no details, and message describes the missing OAuth step. Full flow — Keys and authorization.

How to check a key's state up front: GET /v1/me for a personal key returns a b24Credentials block (ready, and when ready: false the same reason plus actions), and GET /v1/keys returns a b24Ready flag on every key. The /v1/me response is cached for 30 seconds, so right after fixing the Bitrix24 side, request it as GET /v1/me?refresh=tariff — otherwise the previous state is returned for up to half a minute. GET /v1/keys is not cached.

`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 scope set in the Bitrix24 account is narrower than the key's own scope set. Bitrix24 scopes are fixed for the key at issue time, so a scope added to an already issued key shows up in GET /v1/me, while the key still accesses the account's data with its original set.
• The requested module is disabled in the Bitrix24 account (no CRM, no bot platform, and so on).

The fix depends on the key type. When the refusal comes from the scope set, error.hint names the specific case. The hint is not always there: a bare ACCESS_DENIED with no explanation from Bitrix24 may arrive without one.

• API key (vibe_api_). The scope set the key uses to call Bitrix24 is stored on the account side, separately from the set recorded on the key itself. Reissue the key, reconnect it, or create a new one with the scope selected — editing the app's permissions in the account changes nothing in this case.
• Authorization key (vibe_app_). Recreate the application with the required scope and complete authorization again. Reissuing the key does not grant a scope here.
• Chat and bot methods. For these methods the refusal is not explained by scopes alone: the key owner must be an administrator of the Bitrix24 account. Issue the key under an administrator account — widening the scopes will not help here.
• If the cause is the employee's permissions rather than the key's scopes, check the user's permissions in the Bitrix24 entity card.

For the full description of how scopes are fixed to a key, and what to do if the refusal repeats after a reissue, see Keys and authorization.

`WRITE_BLOCKED_READONLY_KEY` (403)

The key is in read-only mode (accessMode: "READONLY"), but the request performs a write. The mode, how to switch it, and the Bitrix24 account policy are described in full 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" in the Access mode block of the relevant key's card, and save. The mode takes effect on the next request — no reissue needed.
• If the toggle in the card is unavailable, the Bitrix24 account administrator has 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.

See also

• Error codes
• Billing and plans
• Keys and authorization
• Access mode
• Management keys
• Scopes
• Retries and error handling in code