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

Подробный разбор кодов, которыми 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_.

Решение:

• Сверить ключ на странице его вида: личный (vibe_api_) — Ключи API, ключ авторизации приложения (vibe_app_) — карточка приложения в разделе Приложения, менеджмент-ключ (vibe_live_) — Менеджмент-ключи. Раздел «Ключи API» показывает только личные ключи, поэтому отсутствие там ключа приложения или менеджмент-ключа не означает, что он удалён.
• Создать новый ключ, если старый действительно удалён.

`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 — для них остаётся создание нового ключа.

Важно: переподключение доступно НЕ каждому ключу: платформа отбивает его ответом 400 RECONNECT_NOT_APPLICABLE для ключей приложений, ключей со служебным назначением (в том числе ключа Коворка), ключей, привязанных к серверу, к живому агенту или к живому управляемому боту, и ключей без скоупов Битрикс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 кэша нет.

`PORTAL_CREDENTIALS_REJECTED` (401)

Битрикс24 отклонил учётные данные, с которыми платформа обращается к порталу от имени ключа. Отличие от TOKEN_MISSING: там учётных данных у ключа нет вовсе, здесь они есть, но портал их больше не принимает — вебхук отозван, удалён на портале или потерял силу вместе с правами владельца.

{
  "success": false,
  "error": {
    "code": "PORTAL_CREDENTIALS_REJECTED",
    "message": "Bitrix24 rejected the credentials this key calls the portal with",
    "hint": "The portal no longer accepts the webhook or token behind this key. Reconnect the key to the portal (or re-issue it) — Retrying will not help until the credentials are restored."
  }
}

Повтор запроса не помогает: пока креды не восстановлены, портал отклоняет каждый вызов этого ключа одинаково. Код приходит на любом маршруте, который читает данные портала, и в подошибке POST /v1/batch.

Что делать: переподключить ключ — POST /api/keys/:id/reconnect — либо, если переподключение к ключу не применимо, создать новый. Ограничения переподключения те же, что у TOKEN_MISSING выше.

Как отличить от отказа по правам: нехватка прав приходит кодами SCOPE_DENIED (403) и BITRIX_ACCESS_DENIED (403) — там креды приняты, но операция закрыта. PORTAL_CREDENTIALS_REJECTED означает, что портал не признал сами креды, и никакая настройка прав этого не изменит.

`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.
• Скоуп ключа сужен на этапе создания.

Решение:

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

Ключ, выданный через Partner Connect, — отдельный случай. Его набор задаёт не форма ключа, а страница согласия, поэтому перевыпуск ничего не добавит: право надо запросить и получить подтверждение пользователя заново. Со стороны приложения — отметить нужное право в карточке приложения и провести пользователя через согласие ещё раз. Новый ключ придёт уже с ним. vibe:ai приложение отмечает само, остальные платформенные права выдаёт платформенный администратор — порядок в разделе Платформенные права. Такой ключ видно по имени в списке ключей: Connect: <название приложения>.

`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"
    }
  }
}

Важно: switchUrl — не константа. В примере выше личный ключ, поэтому путь ведёт на страницу ключей. Раздел «Ключи API» по построению показывает ТОЛЬКО личные ключи, поэтому у остальных видов путь другой: у ключа авторизации приложения (vibe_app_*) — страница «Приложения» /applications, у менеджмент-ключа (vibe_live_*) — /management-keys. Читайте значение из ответа, а не подставляйте своё.

Поля details:

Причины:

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

Решение:

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

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

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