Авторизация, ключи и права

Подробный разбор кодов, которыми API Вайбкод отвечает, когда ключ не опознан, ему не хватает прав или он работает в режиме «только чтение».

Сводная таблица всех кодов API Вайбкод — Коды ошибок.

`MISSING_API_KEY` (401)

Запрос не содержит заголовка X-Api-Key.

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

Причины:

• Не передан заголовок X-Api-Key или Authorization.
• Заголовок передан с пустым значением.

Решение:

• Добавить заголовок X-Api-Key: vibe_api_... или X-Api-Key: vibe_app_....
• Проверить, что переменная окружения с ключом установлена корректно (для CLI-утилит и SDK).

`INVALID_API_KEY` (401)

Переданный ключ не существует или его формат не распознан.

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

Причины:

• Опечатка или лишние пробелы в ключе.
• Ключ удалён владельцем или администратором.
• Ключ от другого окружения — тестового вместо боевого или наоборот.
• Префикс не из числа поддерживаемых: vibe_api_, vibe_app_, vibe_live_.

Решение:

• Сверить ключ в личном кабинете на странице /keys.
• Создать новый ключ, если старый удалён.

`TOKEN_MISSING` (401)

У ключа нет кредов Битрикс24, поэтому вызов к порталу выполнить нечем. Причина зависит от типа ключа, и это два разных сценария.

Личный ключ (vibe_api_*) ходит в портал по вебхуку. Если вебхука на ключе нет, ответ на вызовах сущностей (/v1/{сущность} и POST /v1/batch) несёт машиночитаемую причину в error.details. На остальных маршрутах приходит тот же код без details:

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

Значения details.reason:

Переподключение — POST /api/keys/:id/reconnect: выдаёт ключу вебхук, не меняя саму строку ключа (интеграции перенастраивать не нужно), и снимает авто-блокировку со связанных ботов. Не применимо к ключам приложения, системным ключам и ключам без скоупов Битрикс24 — для них остаётся создание нового ключа.

paywallCode приходит только для тарифных причин. Вместе с ним может прийти upgradeUrl — ссылка на страницу подключения на портале. У INT_TARIFF_REQUIRED её нет.

Те же три условия закрывают установку приложения и привязку места встраивания — там они приходят самостоятельными кодами 403, разбор — Биллинг, тариф и подписка.

Ключ приложения (vibe_app_*) держит токены портала в пользовательской сессии, а не на ключе. Вызов только с X-Api-Key, без Authorization: Bearer <токен сессии>, законно отвечает TOKEN_MISSING — details в этой ветке не приходит, а message описывает пропущенный шаг OAuth. Полный поток — Ключи и авторизация.

Как посмотреть состояние ключа заранее: GET /v1/me для личного ключа отдаёт блок b24Credentials (ready, а при ready: false — та же reason и действия), а GET /v1/keys — признак b24Ready на каждом ключе. Ответ /v1/me кэшируется на 30 секунд, поэтому сразу после починки на портале читайте его как GET /v1/me?refresh=tariff — иначе до полуминуты будет отдаваться прежнее состояние. У GET /v1/keys кэша нет.

`SCOPE_DENIED` (403)

У ключа нет нужного скоупа для запрошенной операции.

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

Причины:

• Для CRM-сущностей нужен скоуп crm, для задач — task, для бот-платформы — imbot, для AI Router — vibe:ai, для инфраструктуры — vibe:infra.
• Скоуп ключа сужен на этапе создания.

Решение:

• Открыть страницу ключа в личном кабинете и выпустить новый ключ с расширенным набором скоупов.
• Полный список скоупов и их назначение — на странице Ключи и авторизация.

`BITRIX_ACCESS_DENIED` (403)

Битрикс24 ответил ACCESS_DENIED: у пользователя или приложения нет прав на сущность или операцию.

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

Причины:

• У пользователя нет прав на сущность в CRM (например, чужая сделка с ограничением видимости).
• Набор скоупов на портале уже, чем набор скоупов ключа. Скоупы Битрикс24 закрепляются за ключом в момент выпуска, поэтому скоуп, добавленный к уже выпущенному ключу, GET /v1/me покажет, а к данным портала ключ обратится с прежним набором.
• Запрашиваемый модуль выключен на портале (отсутствует CRM, бот-платформа и тому подобное).

Решение зависит от типа ключа. Когда отказ вызван набором скоупов, в error.hint приходит подсказка с конкретным случаем. Подсказка приходит не всегда: голому ACCESS_DENIED без пояснений от Битрикс24 её может не быть.

• API-ключ (vibe_api_). Набор скоупов, с которым ключ обращается к порталу, хранится на портале отдельно от набора у самого ключа. Перевыпустить ключ, переподключить его или создать новый с отмеченным скоупом — правка разрешений приложения на портале в этом случае ничего не меняет.
• Ключ авторизации (vibe_app_). Создать приложение заново с нужным скоупом и пройти авторизацию заново. Перевыпуск ключа здесь скоуп не выдаёт.
• Методы чатов и ботов. Для них того же отказа недостаточно объяснить скоупом: владелец ключа должен быть администратором портала. Выпустить ключ под учётной записью администратора — расширение скоупов тут не поможет.
• Если дело в правах сотрудника, а не в скоупах ключа — проверить права пользователя в карточке сущности Битрикс24.

Полное описание того, как скоупы закрепляются за ключом и что делать, если после перевыпуска отказ повторяется, — Ключи и авторизация.

`WRITE_BLOCKED_READONLY_KEY` (403)

У ключа задан режим «только чтение» (accessMode: "READONLY"), а запрос выполняет запись. Полное описание режима, переключения и политики портала — Режим доступа.

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

Причины:

• API-ключ или ключ авторизации (vibe_api_, vibe_app_) в режиме READONLY выполнил вызов, который проксируется в Битрикс24 как операция записи: создание, обновление, удаление, действие над сущностью.
• Менеджмент-ключ (vibe_live_) в режиме READONLY выполнил запрос с HTTP-методом POST, PATCH, PUT или DELETE — например, попытка создать ключ через POST /v1/keys или удалить запись обратной связи.

Решение:

• Владельцу ключа — открыть Ключи API, в карточке нужного ключа в блоке Режим доступа выбрать «Чтение и запись» и сохранить. Режим применяется к следующему запросу, перевыпуск не нужен.
• Если в карточке выбор переключателя недоступен — администратор портала ограничил режим. Запросить у администратора снятие ограничения для этого ключа.
• При работе через AI-агента — действующий режим возвращает GET /v1/me в поле data.accessMode. Если запись нужна постоянно, выпустить отдельный ключ с режимом «чтение и запись».

Смотрите также

• Коды ошибок
• Биллинг, тариф и подписка
• Ключи и авторизация
• Режим доступа
• Менеджмент-ключи
• Скоупы
• Повторы и обработка ошибок в коде