# Коды ошибок

Справочник кодов ошибок API Вайбкод: единый формат ответа, перечень кодов, типичные причины и способы устранения. Применяется ко всем эндпоинтам `/v1/...`.

## Разделы документации

- [Авторизация, ключи и права](/docs/errors/auth) — `MISSING_API_KEY`, `INVALID_API_KEY`, `TOKEN_MISSING`, `SCOPE_DENIED`, `BITRIX_ACCESS_DENIED`, `WRITE_BLOCKED_READONLY_KEY`
- [Запрос и данные](/docs/errors/request) — `VALIDATION_ERROR`, `INVALID_PARAMS`, `MISSING_REQUIRED_FILTER`, `BATCH_LIMIT_EXCEEDED`, `ENTITY_NOT_FOUND`
- [Биллинг, тариф и подписка](/docs/errors/billing) — `BILLING_EXHAUSTED`, `COMMERCIAL_PLAN_REQUIRED`, `B24_MARKET_SUBSCRIPTION_REQUIRED`, `B24_MARKET_TRIAL_USED`, `INT_TARIFF_REQUIRED`
- [Лимиты, очереди и паузы](/docs/errors/limits) — `RATE_LIMITED`, `CALLER_RATE_LIMITED`, `ERROR_LOOP_DETECTED`, `QUEUE_OVERFLOW`, `QUEUE_TIMEOUT`, `TIMEOUT_QUARANTINE`, `OPERATION_TIME_LIMIT`
- [Битрикс24 и платформа](/docs/errors/platform) — `BITRIX_ERROR`, `METHOD_NOT_YET_AVAILABLE`, `BITRIX_UNAVAILABLE`, `BITRIX_TIMEOUT`, `INTERNAL_ERROR`
- [Что безопасно повторять](/docs/errors/retry-safety) — дошёл ли целевой вызов до Битрикс24 и что делать с чтением или записью по каждому временному коду
- [Повторы и обработка ошибок в коде](/docs/errors/handling) — когда повторять запрос, а когда сначала перечитать сущность

## Формат ответа при ошибке

Каждый ответ с ошибкой возвращается в едином виде. `error` — объект.

```json
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Элемент не найден"
  }
}
```

| Поле | Тип | Обяз. | Описание |
|------|-----|:-----:|----------|
| `success` | boolean | да | При ошибке всегда `false` |
| `error.code` | string | да | Машиночитаемый код ошибки. Используйте для различения типов ошибок в коде клиента |
| `error.message` | string | да | Описание ошибки для разработчика. Язык заранее не известен и зависит от источника: технические сообщения платформы приходят на английском, сообщения от Битрикс24 — на языке портала, сообщения о сбоях облачного провайдера локализуются под язык пользователя. Не разбирайте текст и не полагайтесь на его язык — ветвитесь по `error.code` |
| `error.hint` | string \| object | нет | Подсказка для разработчика: что попробовать дальше, на какие пределы обратить внимание. Строка с текстом либо объект, и объектная форма приходит там, где у отказа есть готовый рецепт. При создании инфраструктуры `POST /v1/infra/servers` это поля `reason`, `recovery` и `example` — в `example` готовое тело запроса для исправления. У `413 INLINE_SOURCE_TOO_LARGE` — сразу на трёх маршрутах: выкладка кода, загрузка файла и создание сервера — объект несёт четыре строки: `reason` (почему отказано и какой потолок), `recovery` (каким путём отправить тот же архив), `recoveryAction` (то же действие одной строкой) и `note` (что помогает независимо от выбранного пути) |
| `error.userMessage` | string | нет | Сообщение для конечного пользователя на русском языке. Появляется в биллинговых, инфраструктурных и тарифных ошибках, при перегрузке очереди портала, в отказах лимитера рабочего времени портала и в отказах по скоупу ключа (`error.cause` = `key_scope_missing`): там оно называет недостающее право и место, где его добавляют, и показывается человеку как есть |
| `error.alternatives` | array | нет | Пути решения отказа: оформить тариф, пополнить баланс, обратиться к своей AI-модели по своему ключу. Каждый элемент несёт `type`, а вместе с ним ссылку `url` или описание `description`. Приходит в отказах по тарифу, подписке и балансу |
| `error.details` | object | нет | Машиночитаемый контекст отдельных кодов. Примеры: `reason` в `INVALID_STATE` и в `ROUTE_NOT_FOUND`, `deployableKeys` в `INFRA_FORBIDDEN_FOR_COWORK_KEY`, `upgradeUrl` в отказах по подписке, `method` и `switchUrl` в `WRITE_BLOCKED_READONLY_KEY`. Набор полей зависит от кода — читайте его описание |
| `error.warning` | string | нет | Появляется при повторяющихся одинаковых ошибках на одном ключе — вероятный признак ошибки в коде клиента. Счётчик эвристический, поэтому предупреждение не гарантирует наличие ошибки |
| `error.retryAfter` | number | нет | Секунды до следующей попытки. Появляется в `429` очереди портала (`QUEUE_OVERFLOW`, `QUEUE_TIMEOUT`), в паузах `OPERATION_TIME_LIMIT` и `TIMEOUT_QUARANTINE` и в транзиентных `503` (`BITRIX_TIMEOUT`, `POOL_EXHAUSTED`, `DB_TRANSIENT`, `SERVICE_UNAVAILABLE`). У `ERROR_LOOP_DETECTED` поле и заголовок `Retry-After` содержат остаток паузы до следующей пробы. Если время уже истекло, но вызов ещё блокируется, — 60 секунд до повторной проверки. У одиночного `RATE_LIMITED` поля в теле нет — срок приходит заголовком `Retry-After`. У сформированной платформой подошибки пакета с этим кодом срок приходит полем `retryAfter` в `data.errors.<id>` или `data[i].error`: отдельного заголовка для подвызова нет. У `LARGE_BODY_BACKEND_BUSY` поле приходит не на всех путях отказа — там тоже берите срок из заголовка |
| `error.b24Code` | string | нет | Машиночитаемый код причины от Битрикс24 в ответах `422 BITRIX_ERROR`; у роутов чатов на мессенджере v2 — [загрузки чата](/docs/chats/messages/load), [счётчиков](/docs/chats/discovery/counters), [сообщений вокруг сообщения](/docs/chats/messages/context), режима `format=v2`, [ссылок и гостей](/docs/chats/sharing), [стикеров](/docs/chats/stickers), [формы задачи для чата](/docs/chats/service/task-form) и [для сообщения](/docs/chats/service/task-form-message), [формы потока](/docs/chats/service/flow-form) и [Zoom](/docs/chats/service/zoom) — ещё и в `404 ENTITY_NOT_FOUND`. Приходит не всегда — только когда Битрикс24 прислал отдельный код |
| `error.release` | string | нет | Идентификатор обновления Битрикс24, которого ждёт портал: имя модуля и номер версии одной строкой, например `imopenlines 26.700.0`. Приходит только в [`METHOD_NOT_YET_AVAILABLE`](/docs/errors/platform#method_not_yet_available-422) |
| `error.scope` | string | нет | Область отказа: `"apiKey"` — вызывающий ключ, `"portal"` — аккаунт Битрикс24. Конкретные ограничения и правила повтора определяются `error.code`. `"apiKey"` приходит в [`ERROR_LOOP_DETECTED`](/docs/errors/limits#error_loop_detected-429), [`OPERATION_TIME_LIMIT`](/docs/errors/limits#operation_time_limit-429), [`TOKEN_REFRESH_FAILED`](/docs/errors/auth#token_refresh_failed-401), [`PORTAL_CREDENTIALS_REJECTED`](/docs/errors/auth#portal_credentials_rejected-401) и [`PORTAL_ADDRESS_CHANGED`](/docs/errors/auth#portal_address_changed-409). `"portal"` приходит в [`QUEUE_OVERFLOW`](/docs/errors/limits#queue_overflow-429), [`QUEUE_TIMEOUT`](/docs/errors/limits#queue_timeout-429), [`RATE_LIMITED`](/docs/errors/limits#rate_limited-429) при отказе Битрикс24, [`BITRIX_TIMEOUT`](/docs/errors/platform#bitrix_timeout-503) и [`TIMEOUT_QUARANTINE`](/docs/errors/limits#timeout_quarantine-429). [`FEEDBACK_QUOTA_EXCEEDED`](./feedback/submit.md) использует оба значения |
| `error.cause` | string | нет | Причина отказа в доступе. `b24_permission` — у пользователя Битрикс24, от имени которого идёт вызов, нет прав. `b24_scope` — учётным данным ключа не хватает скоупа Битрикс24. `key_scope_missing` — у самого ключа API нет скоупа, который нужен маршруту. `bot_other_key` — бот привязан к другому ключу API. `unknown` — причину нельзя установить однозначно. Набор открытый: незнакомое значение читайте как `unknown`. Приходит в `403 BITRIX_ACCESS_DENIED`, в `403 BOT_ACCESS_DENIED` и в `422 BITRIX_ERROR` с `b24Code` `ACCESS_DENIED_EXTEND` или `NO_AUTH_FOUND`. `key_scope_missing` приходит в `403 INSUFFICIENT_SCOPE`, `403 INFRA_SCOPE_REQUIRED`, `403 SCOPE_NOT_ALLOWED` пакетного запроса и в `403 SCOPE_DENIED` маршрутов сущностей (включая их пакетные и агрегатные вызовы и `include`), записей таймлайна и открытых линий. Разбор — [Авторизация, ключи и права](/docs/errors/auth#bitrix_access_denied-403) |
| `error.method` | string | нет | Метод Битрикс24, на котором случился отказ, не длиннее 100 символов. Приходит вместе с `error.cause`, когда метод известен |
| `error.requiredScope` | string | нет | Скоуп, которого не хватило. При `error.cause` = `b24_scope` — скоуп Битрикс24, и только когда скоуп метода известен. При `error.cause` = `key_scope_missing` — скоуп, который нужен маршруту или вызову пакета; в ответе на пакет, вызовам которого нужны разные скоупы, не приходит |
| `error.keyScopes` | array | нет | Скоупы ключа, действующие в этом запросе, — вместе с выданными автоматически `vibe:ai` и `vibe:search`, поэтому набор бывает шире `data.scopes` из `GET /v1/me`. Приходит только при `error.cause` = `key_scope_missing`. В элементах `data.errors` пакетного запроса не повторяется |
| `error.fix` | object | нет | Что снимает отказ: `action` — действие, `via` — где оно совершается. При `via: "same_key"` приходят ещё `path` — готовый маршрут без подстановок — и `body` — готовое тело запроса к нему. Приходит вместе с `error.cause`. `action: "none"` значит, что машинного действия нет, — читайте `error.hint`. Наборы `action` и `via` открытые: незнакомое `action` читайте как `none`, незнакомое `via` — как шаг человека. Значения — [Авторизация, ключи и права](/docs/errors/auth#bitrix_access_denied-403) |

Пример ответа с дополнительным полем `hint` (`429 RATE_LIMITED`) — срок повтора здесь приходит только заголовком `Retry-After: 2`:

```json
{
  "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."
  }
}
```

В одиночном HTTP-ответе заголовок `Retry-After` дублирует значение `error.retryAfter`, когда поле есть, для совместимости со стандартом HTTP. Некоторые отказы передают срок только заголовком — в одиночном ответе опирайтесь на него. У подошибки внутри успешного пакетного ответа отдельного заголовка нет: если срок передан, берите его из `retryAfter` этой подошибки.

## Сводная таблица кодов

Таблица покрывает основные коды, которые встречаются на любом эндпоинте API Вайбкод. Доменные коды (`BOT_NOT_FOUND`, `SERVER_NOT_RUNNING`, `AGENT_LIMIT_REACHED` и подобные) описаны на страницах соответствующих разделов.

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

| Код | HTTP | Когда возникает |
|-----|------|-----------------|
| `MISSING_API_KEY` | 401 | Запрос без заголовка `X-Api-Key` |
| `INVALID_API_KEY` | 401 | Платформа не знает такой строки ключа: опечатка, обрезанное при копировании значение, ключ от другого окружения или удалённый ключ. Существующий ключ, который перестал работать, отвечает другими кодами — `KEY_INACTIVE`, `KEY_EXPIRED`, `PORTAL_CREDENTIALS_REJECTED` |
| `KEY_INACTIVE` | 401 | Ключ найден, но отозван или заблокирован платформой. Строка ключа прежняя, и новый ключ выдаётся отдельно — восстановить отозванный нельзя |
| `KEY_EXPIRED` | 401 | Ключ найден, срок действия из `expiresAt` прошёл. Поле `status` при этом остаётся `ACTIVE` |
| `INVALID_APP_KEY` | 401 | OAuth-ручка получила `app_key`, который не найден или не принадлежит OAuth-приложению |
| `WRONG_AUTH_SCHEME` | 401 | API-ключ передан в заголовке `Authorization: Bearer`. Ключ OAuth-приложения (`vibe_app_*`) передаётся в `X-Api-Key`, а `Authorization: Bearer` несёт сессионный токен (`vibe_session_*`). Клиенту, который умеет только Bearer, используйте личный ключ (`vibe_api_*`) — он принимается в `Authorization: Bearer` |
| `TOKEN_EXPIRED` | 401 | Срок действия OAuth-токена истёк |
| `TOKEN_REFRESH_FAILED` | 401 | Не удалось обновить OAuth-токен на стороне Битрикс24 |
| `PORTAL_CREDENTIALS_REJECTED` | 401 | Битрикс24 отклонил учётные данные, с которыми ключ обращается к порталу: вебхук ключа отозван или потерял силу. Повтор не помогает — ключ нужно переподключить |
| `PORTAL_ADDRESS_CHANGED` | 409 | Коробочный портал переехал на новый адрес, а вебхук ключа выписан на прежний. Платформа не отправляет секрет туда, где портала больше нет, поэтому вызов отклоняется до обращения к порталу. Повтор не помогает — переподключите ключ: платформа перевыпустит вебхук, строка ключа и его права не изменятся |
| `WRONG_KEY_TYPE` | 401 | Тип ключа не подходит к эндпоинту: например, менеджмент-ключ на маршруте сущности |
| `WRONG_KEY` | 403 | Сервер существует, но вызывающему не принадлежит. Операции над содержимым приложения — [выкладка](./infra/deploy/deploy.md), [команда](./infra/deploy/exec.md), [загрузка файла](./infra/deploy/upload.md) и [чтение логов](./infra/deploy/logs.md) — открыты по любому из трёх оснований: управляющий ключ сервера, ключ, приложение которого привязано к этому серверу, либо членство в команде разработки этого сервера. Токены доступа и загрузка значка требуют управляющего ключа. Управление машиной открыто ещё и роли «Администратор» команды разработки. В ответе — `hint` с восстановлением из двух шагов: перепривязать сервер в кабинете и сменить ключ, которым обращается клиент. Подробнее — [восстановление доступа](./infra/server-access-recovery.md) |
| `TOKEN_MISSING` | 401 | У ключа нет кредов Битрикс24. Для личного ключа (`vibe_api_*`) — нет вебхука портала: на маршрутах сущностей и в `POST /v1/batch` причина приходит в `error.details`, на остальных маршрутах приходит тот же код без `details`. Для ключа приложения (`vibe_app_*`) — не передан `Authorization: Bearer` с токеном сессии |
| `SESSION_REQUIRED` | 401 | Операция с [местами встраивания](./apps/placements.md) выполнена без заголовка `Authorization: Bearer` с токеном сессии там, где аккаунт его требует |
| `SESSION_APP_MISMATCH` | 403 | Сессия в `Authorization: Bearer` выписана другому приложению или другому аккаунту Битрикс24, чем ключ в `X-Api-Key`. Передайте ключ авторизации того приложения, которое выписало сессию через [`POST /v1/oauth/token`](./keys-auth/oauth.md) |
| `PERSONAL_KEY_WEBHOOK_SCOPES_INVALID` | 400 | Выписка, обновление или перевыпуск ключа портала, где `placement` и `entity` запрошены, а кроме них в наборе прав ничего нет. Ключ портала стоит на входящем вебхуке Битрикс24, а такие права вебхук не несёт — добавьте право на данные либо заведите OAuth-приложение. Подробнее — [менеджмент-ключи](./management-keys.md) |
| `ACCOUNT_PENDING_ERASURE` | 503 | Аккаунт владельца ключа ждёт удаления данных — на это время ключ заморожен. В ответе заголовок `Retry-After: 3600`. Действует на любой ключ владельца, включая [менеджмент-ключ](./management-keys.md). Отмена запроса на удаление возвращает ключу работу, перевыпускать его не нужно |

Причины и порядок действий по `MISSING_API_KEY`, `INVALID_API_KEY` и `TOKEN_MISSING` — [Авторизация, ключи и права](/docs/errors/auth).

### Состояние аккаунта Битрикс24

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

| Код | HTTP | Когда возникает |
|-----|------|-----------------|
| `PORTAL_SUSPENDED` | 403 | Аккаунт приостановлен |
| `PORTAL_DELETED` | 403 | Аккаунт удалён |
| `PORTAL_BLOCKED` | 403 | Аккаунт заблокирован. Рядом с кодом приходит `blockedAt` — момент блокировки в формате ISO 8601. Причину блокировки ответ не раскрывает |
| `NO_PORTAL` | 401 | Ключ не привязан ни к одному аккаунту. Исключение — маршруты [хранилища](./storage.md): непривязанный ключ получает там `403 STORAGE_REQUIRES_PORTAL_BINDING`. Тот же код с HTTP `500` приходит на маршрутах [авторизации пользователей приложения](./keys-auth/oauth.md) и означает там другое — приложение не связано с аккаунтом |

### Авторизация пользователей приложения (OAuth)

| Код | HTTP | Когда возникает |
|-----|------|-----------------|
| `INVALID_REDIRECT_URI` | 400 | `redirect_uri` не зарегистрирован у приложения на входе `GET /v1/oauth/authorize` |
| `INVALID_STATE` | 400 | `state` не найден или истёк за 20 минут на приёме ответа Битрикс24. В `error.details.reason` — `NOT_FOUND` или `EXPIRED` |
| `INVALID_CODE` | 400 | Код авторизации не найден или принадлежит другому приложению |
| `CODE_EXPIRED` | 400 | Срок действия кода авторизации прошёл — 5 минут |
| `CODE_ALREADY_USED` | 400 | Код авторизации уже обменян на токен сессии |
| `REDIRECT_URI_MISMATCH` | 400 | `redirect_uri` при обмене кода не совпадает с переданным на входе |
| `DOMAIN_MISMATCH` | 400 | `domain` в `POST /v1/oauth/placement-session` не совпадает с порталом приложения |
| `USER_AUTH_REQUIRED` | 401 | Токен пользователя Битрикс24 не подтвердил авторизацию на портале |
| `MISSING_TOKEN` | 400 | `POST /v1/oauth/revoke` без заголовка `Authorization: Bearer` с токеном сессии |

Отказ на приёме возврата может прийти не кодом, а параметром `?error=` в адресе `redirect_uri` — `token_exchange_failed`, `invalid_domain` или `profile_fetch_failed`.

Полное описание потока — [Авторизация пользователей приложения](./keys-auth/oauth.md).

### Права и скоупы

| Код | HTTP | Когда возникает |
|-----|------|-----------------|
| `SCOPE_DENIED` | 403 | У ключа нет нужного скоупа (например, `crm` для сделок, `imbot` для ботов). Если ответ несёт `error.cause` = `key_scope_missing`, действие — в `error.fix`, текст для человека — в `error.userMessage` |
| `WRITE_BLOCKED_READONLY_KEY` | 403 | У ключа задан режим «только чтение», а вызов выполняет запись |
| `INFRA_FORBIDDEN_FOR_COWORK_KEY` | 403 | Ключ Cowork/Code со скоупом `vibe:cowork` работает только с данными: изменяющие операции ему закрыты — все методы `/v1/infra/*`, кроме чтений `GET`, все изменяющие операции над приложениями (создание, правка, удаление, перепривязка, публикация и снятие с публикации) и запись в депо исходников. На `POST /v1/portals/:id/activate-market-trial` тот же код получает агентский seat-ключ, а ключу десктопа этот эндпоинт отвечает раньше и другим кодом — `PURPOSE_KEY_FORBIDDEN`, разбор на странице [Активировать пробный период Маркета](/docs/activate-market-trial). Собственный эндпоинт Cowork/Code `POST /v1/cowork/activate-market-trial` этого кода не отдаёт вовсе. Порядок действий — [Проектный ключ для деплоя](/docs/cowork/deploy-key). Ключу подписки, выписанному для стороннего агента, проектный ключ не выдаётся (`403 COWORK_HARNESS_KEY_FORBIDDEN`), поэтому ему `error.details.requiredAction` называет настольное приложение Cowork/Code и обычный ключ со скоупом `vibe:infra`, разбор на странице [Свой агент на подписке](/docs/cowork/harness). В `error.details.deployableKeys` ответ перечисляет ваши другие активные ключи с правом деплоя — `name`, `prefix`, `suffix`, до пяти |
| `INFRA_SCOPE_REQUIRED` | 403 | У ключа нет скоупа `vibe:infra` — управление инфраструктурой недоступно. Добавьте скоуп или используйте ключ с правами на инфраструктуру. Действие — в `error.fix`: пока работа с серверами на портале выключена, скоуп не добавить, и `fix.action` приходит `none`. `fix.via` = `platform` значит, что работу с серверами выключила платформа. Отсутствие `via` при `action` = `none` означает только «места для машинного действия нет» и причину НЕ называет: так же отвечают и другие отказы по этому скоупу — работу с серверами выключил администратор портала, определить это не удалось, происхождение ключа не установлено, ключ выдан через [Partner Connect](/docs/partner-connect). Причину различает текст `error.userMessage` и `error.hint`, а не `via` |
| `INFRA_DISABLED_FOR_PORTAL` | 403 | Право `vibe:infra` явно запрошено при [создании ключа](/docs/management-keys) или [приложения](/docs/apps/create) либо добавлено правкой их прав, а администратор портала выключил работу с серверами. Проверка считает добавление права, а не его присутствие в теле: правка ключа или приложения, которые это право уже несут, проходит и на закрытом портале, снятие права разрешено всегда. Не путать с `INFRA_SCOPE_REQUIRED` — тот про вызов инфраструктуры ключом без права, этот про саму выдачу права |
| `ONEC_ACCESS_REQUIRED` | 403 | Право `vibe:onec` запрошено при создании ключа или приложения либо добавлено правкой их прав, а у владельца ключа или автора приложения нет доступа к 1С. Доступ к 1С выдаёт администратор портала. Правка ключа или приложения, которые это право уже несут, проходит без проверки. Если проверить доступ не удалось, право выдаётся |
| `SERVER_ROLE_FORBIDDEN` | 403 | Вы состоите в команде разработки сервера, но операция шире вашей роли: роль «Разработчик» покрывает работу с кодом, роль «Администратор» — ещё и управление машиной. В `error.hint` приходят `yourRole`, `requiredRole`, отказанное действие `deniedAction` и список открытых вам вызовов `allowedHere`. Доступ не сломан и не требует ни выдачи заново, ни перепривязки ключа — либо продолжайте по вызовам из `allowedHere`, либо попросите владельца выполнить эту операцию. Разбор ролей — [Список серверов](./infra/servers/list.md) |
| `KEY_POLICY_READONLY_REQUIRED` | 403 | Политика портала разрешает обычным пользователям создавать только ключи с режимом «только чтение» — выпуск ключа с записью отклонён |
| `RATE_LIMIT_ADMIN_ONLY` | 403 | Запрос меняет собственный поминутный лимит ключа на AI-вызовы — поле `rateLimit` при создании или правке, — а вызывающий не администратор портала. Через `POST /v1/keys` и `PATCH /v1/keys/:id` смена этого поля отклоняется и администратору: значение задаётся в личном кабинете. Передача текущего значения без изменения проходит, поэтому клиент, отправляющий объект ключа целиком ради переименования, этого отказа не получает. Оставьте поле пустым, и действует общий лимит платформы — [Лимиты запросов](/docs/keys-auth#лимиты-запросов) |
| `MANAGEMENT_KEY_READ_ONLY` | 403 | Менеджмент-ключ создаёт обращение — `POST /v1/feedback` или загрузка вложения к нему. Чтение и обновление обращений таким ключом доступны, создание — нет. Запрет записи по режиму доступа ключа приходит другим кодом — `WRITE_BLOCKED_READONLY_KEY` |
| `MANAGEMENT_KEY_NO_ENTITY_ACCESS` | 403 | Менеджмент-ключ обращается к эндпоинту сущности — нужен ключ приложения с нужным скоупом |
| `BITRIX_ACCESS_DENIED` | 403 | Битрикс24 отказал в доступе. Нехватка прав у пользователя Битрикс24 — лишь одна из причин: отказ даёт и нехватка скоупа у ключа. Вид отказа приходит в `error.cause`, действие — в `error.fix` |
| `BOT_ACCESS_DENIED` | 403 | Бот привязан к другому ключу API. `error.cause` — `bot_other_key`. Если вызывающий ключ может сам перенести бота на себя, `error.fix` — `transfer_bot` с готовыми `path` и `body`. Разбор — [Авторизация, ключи и права](/docs/errors/auth#bot_access_denied-403) |
| `B24_MARKET_SUBSCRIPTION_REQUIRED` | 403 | Вызов существующего бота остановлен локально: Битрикс24 отклонил Bot REST из-за неактивной подписки Маркетплейса. Остановите опрос и обновите состояние тарифа после продления |
| `OAUTH_REQUIRED` | 403 | Эндпоинт требует пользовательский контекст — нужен ключ типа `vibe_app_*` + Bearer-токен |
| `WAITLIST_PENDING` | 403 | Аккаунт ожидает активации в списке ожидания |
| `OAUTH_SCOPE_CHANGE_REQUIRES_REISSUE` | 403 | Попытка добавить право Битрикс24 к OAuth-app-ключу (`vibe_app_*`) через `PATCH /v1/keys/:id` или к приложению через `PATCH /v1/apps/:id`. Права OAuth-приложения фиксируются при выпуске — снятие прав работает, а добавление нет. Новое право даёт перевыпуск ключа авторизации в кабинете: он выдаёт ключ с расширенным набором, после чего аккаунт проходит авторизацию заново. Второй путь — создать приложение сразу с нужным набором |
| `OAUTH_APP_REQUIRED` | 400 | Операция с [местами встраивания](./apps/placements.md) выполнена личным ключом `vibe_api_*`. Привязка, отвязка и список привязанных мест доступны только ключу авторизации приложения `vibe_app_*` |
| `PLACEMENT_SCOPE_MISSING` | 403 | У ключа нет скоупа `placement` — [привязка и отвязка мест встраивания](./apps/placements.md) недоступны |
| `SESSION_REQUIRES_ADMIN` | 403 | Привязка места встраивания на коробочном аккаунте выполняется под учётной записью без прав администратора аккаунта |
| `B24_EMBEDDING_APP_NOT_FOUND` | 404 | Битрикс24 не знает идентификатор приложения: локальное приложение на аккаунте удалили или переустановили. Создайте локальное приложение заново и вызовите `POST /v1/apps/:id/relink-oauth` с новыми `bitrixClientId` и `bitrixClientSecret`. Не путать с `APP_NOT_FOUND` — тот про связку ключа и приложения на стороне платформы Вайбкод |
| `B24_EMBEDDING_INSTALL_DENIED` | 403 | Битрикс24 отказал в установке встройки при действующей подписке: у пользователя, чьим ключом разработчика идёт вызов, нет права ставить локальные приложения и/или нет доступа к самому приложению. Подписка считается действующей в двух случаях — её подтвердил Битрикс24 либо проверку выполнить не удалось, а аккаунт уже числится подписанным в Вайбкод. Если действующей подписки нет ни по одному из источников, тот же отказ приходит как `502` |
| `APP_NOT_REGISTERED` | 400 | У приложения нет идентификатора приложения Битрикс24 — [привязать или отвязать место встраивания](./apps/placements.md) нельзя |
| `BOX_NO_DEVELOPER_KEY` | 400 | У автора приложения не настроен ключ разработчика — операция с местами встраивания на коробочном аккаунте недоступна |
| `OAUTH_APP_KEY_CANNOT_RELINK` | 403 | `POST /v1/apps/:id/relink-oauth` вызван ключом самого OAuth-приложения (`vibe_app_*`). Перепривязывать учётные данные приложения таким ключом нельзя — используйте личный ключ (`vibe_api_*`) или кабинет |

Причины и порядок действий по `SCOPE_DENIED`, `BITRIX_ACCESS_DENIED` и `WRITE_BLOCKED_READONLY_KEY` — [Авторизация, ключи и права](/docs/errors/auth).

### Валидация запроса

| Код | HTTP | Когда возникает |
|-----|------|-----------------|
| `VALIDATION_ERROR` | 400 | Тело или query-параметры не прошли проверку схемы. `message` содержит подробности по полям |
| `INVALID_JSON_BODY` | 400 | Тело запроса не разбирается как JSON. Приходит до проверки схемы, поэтому полей в `message` нет. Этот код возвращают маршруты сущностей `/v1/<сущность>`, а также `/v1/apps`, `/v1/bots`, `/v1/keys`, `/v1/note`, все операции сервера `/v1/infra/servers/:id`, `/v1/infra/runtimes`, маршруты пользовательских полей, чатов `/v1/chats/*` и открытых линий `/v1/openlines/*` |
| `FST_ERR_CTP_INVALID_JSON_BODY` | 400 | Тот же случай — тело не разбирается как JSON — на остальных маршрутах: [`POST /v1/search`](./search/run.md), [`POST /v1/research`](./search/research.md), [`POST /v1/batch`](./batch.md) и прочих |
| `CATALOG_NOT_ELIGIBLE` | 400 | Карточка в каталоге приложений Битрикс24 для этого сервера невозможна: нет субдомена, приложение ещё не выкладывали, это рантайм агента, хост галактики, либо у сервера нет управляющего ключа или портала. См. [Опубликовать в каталоге](./infra/servers/b24-catalog-publish.md) |
| `CATALOG_ORPHANED` | 400 | Карточку в каталоге удалили на стороне портала. Восстановление доступно в личном кабинете, на публичном API — нет |
| `fst_err_ctp_invalid_json_body` | 400 | Тот же случай на OpenAI-совместимых маршрутах [AI Router](./ai.md) — `/v1/ai/`, `/v1/chat/`, `/v1/models`, `/v1/audio/`. На них коды приводятся к нижнему регистру, а ответ идёт в OpenAI-конверте: `error.type`, `error.code`, без поля `success` |
| `INVALID_PARAMS` | 400 | Битрикс24 вернул `INVALID_PARAMS` либо отклонил вызов до запуска метода, не найдя значения обязательного параметра (`Could not find value for parameter`) — тогда параметр назван в `error.hint`; обработчик маршрута нашёл некорректное значение параметра; на записи в поле-скаляр передан объект или массив. См. [Запрос и данные](/docs/errors/request) |
| `INVALID_REQUEST` | 400 | Структура запроса не соответствует требуемой — например, `calls` в `/v1/batch` пустой массив или содержит больше 50 элементов, [создание сервера](./infra/servers/create.md) без обязательных полей, не-объект вместо тела на маршрутах пользовательских полей, не-объект (`null`, массив, строка, число, boolean) вместо тела на `POST /{entity}/search` |
| `MISSING_PARAMS` | 400 | Не передан обязательный параметр, явно перечисленный в схеме эндпоинта |
| `MISSING_REQUIRED_FILTER` | 400 | Не передан обязательный фильтр для list-эндпоинтов, требующих контекста: `timelines` (`entityType` + `entityId`), `catalog-products` и `catalog-sections` (`iblockId`), `catalog-product-property-enums` (`propertyId`). Он же приходит на [агрегацию дел](./entities/activities/aggregate.md) без сужающего фильтра — там достаточно одного сужения из нескольких, и `message` их перечисляет |
| `MISSING_REQUIRED_PARAMS` | 400 | Не переданы обязательные параметры контекста для поиска или списка вложенных данных: `files` требует `folderId`, `folders` — `parentId`, `calendar-events` — `type` и `ownerId`. `message` перечисляет недостающие поля |
| `MISSING_REQUIRED_FIELDS` | 400 | Не передано поле тела, объявленное обязательным при создании сущности. `message` называет недостающее поле |
| `MISSING_FIELD` | 400 | Создание [пользовательского поля](./userfields.md) без `userTypeId`. `message` приводит примеры допустимых типов |
| `EMPTY_CREATE_BODY` | 400 | Тело запроса на создание пустое — не передано ни одного поля. Тот же код и для тела, которое вовсе не является JSON-объектом (`null`, массив, строка, число, boolean) — ни одно распознаваемое поле в нём найти нельзя в принципе |
| `EMPTY_UPDATE_BODY` | 400 | Тело запроса на обновление пустое — не передано ни одного поля. Тот же код и для тела, которое вовсе не является JSON-объектом (`null`, массив, строка, число, boolean) |
| `NESTED_FIELDS_ENVELOPE` | 400 | На маршруте записи сущности, который сам оборачивает поля в `fields`, передан объект `fields`, хотя схема не объявляет такое поле. Этот вызов не записывается; передайте поля плоско в корне JSON. В смешанном глобальном batch другие допустимые вызовы могут выполниться. Глобальный batch ставит код в ошибку вызова; импорт и пакетный маршрут сущности сохраняют свои коды `IMPORT_ITEM_VALIDATION` / `BATCH_ITEM_VALIDATION` и указывают `NESTED_FIELDS_ENVELOPE` в сообщении. См. [Запрос и данные](./errors/request.md) |
| `INVALID_FILTER_FIELD` | 400 | Имя поля фильтра начинается с родного префикса Битрикс24 `@` (IN) или `!@` (NOT IN) — используйте операторы `$in` / `$nin` |
| `INVALID_DUPLICATE_FILTER_FIELD` | 400 | Два условия в одном фильтре сводятся к одному имени фильтра Битрикс24, поэтому второе молча заменило бы первое: имя из схемы и родное имя Битрикс24, разный регистр, два написания одного оператора, парные имена полей даты (`updatedAt`/`updatedTime`, `createdAt`/`createdTime`). Ещё две пары зависят от сущности: `UF_`-форма вместе с camelCase-написанием складывается только у сущностей со старым стилем именования и только для того написания, которое платформа переводит: чисто буквенное (`ufCrmProjectCode`) — везде на таких сущностях, а с цифровым хвостом (`ufCrm_1698325419`) — лишь у реквизитов; на остальных сущностях цифровая пара отказа не даёт, а связка `$ne` с `$nin` даёт один префикс `!` у ВСЕХ сущностей, кроме элементов CRM (границы разные). `message` называет оба условия и общее имя. Пришлите одно из двух. Операторы, дающие разные имена, по-прежнему допустимы — см. [Одно поле — одно написание](/docs/filtering#одно-поле-одно-написание) |
| `UNKNOWN_FILTER_FIELD` | 400 | Фильтрация по полю, которого нет в схеме сущности (для сущностей с полной схемой полей). Когда поле отклонил валидатор Вайбкод, `message` перечисляет допустимые имена после слова `Available`. Когда поле отклонил Битрикс24, список полей приходит в `error.hint` |
| `UNKNOWN_SELECT_FIELD` | 400 | Отбор полей `select` по имени, которого нет у сущности. Отклоняется на сущностях, чей набор полей выверен по Битрикс24 — их список в описании параметра `select` в [обзоре API](./entity-api.md). `message` перечисляет допустимые имена после слова `Available`. На остальных сущностях запрос выполняется, а имя перечисляется предупреждением в `meta.warnings`. Третий исход — список и поиск реквизитов и банковских реквизитов: эти двери передают имя дальше в Битрикс24, поэтому исход задаёт он — аккаунт, где такого поля нет, отклоняет весь вызов с `422 BITRIX_ERROR`, аккаунт, который имя принял, отвечает предупреждением. Чтение одной записи у тех же сущностей отбирает поля на стороне Вайбкод и отвечает предупреждением всегда. Рядом со значением `*` незнакомое имя не отклоняется нигде — приходит предупреждение. Не сверяются со статической схемой пользовательские поля (`UF_*`, `ufCrm*`), точные дополнительные поля конкретного метода, свойства товаров на своей сущности (`PROPERTY_295` — на товарах, `property295` — на товарах каталога, головных товарах, вариациях и услугах каталога) и связи SPA вида `parentIdN`; они передаются методу без `UNKNOWN_SELECT_FIELD`. Для этих имён отсутствие предупреждения не доказывает, что поле существует или что метод понимает его написание |
| `SELECT_FIELD_NOT_RETURNED` | 400 | Отбор полей `select` по имени, которое у сущности ЕСТЬ, но никогда не возвращается: `GET /v1/{entity}/fields` показывает его с `notReturned: true`. Отдельный код нужен потому, что `UNKNOWN_SELECT_FIELD` утверждает «такого имени нет», а справочник сущности это имя публикует. Уберите его из `select` — остальные поля придут в ответе |
| `UNKNOWN_SORT_FIELD` | 400 | Сортировка по несуществующему полю (для сущностей, у которых валидатор сортировки активен) |
| `UNKNOWN_STAGE` | 400 | Создание сделки или лида со стадией, которой нет в справочнике аккаунта: [`POST /v1/deals`](./entities/deals/create.md) сверяет `stageId` со стадиями воронки из `categoryId` (без него — основной, `DEAL_STAGE`), [`POST /v1/leads`](./entities/leads/create.md) — `stageId` / `statusId` со статусами лидов (`STATUS`). Сравнение буквальное, как у Битрикс24: регистр, пробелы и префикс воронки `C{categoryId}:` должны совпадать со справочником, стадия другой воронки без её `categoryId` тоже не подходит. Запись НЕ создаётся. `message` называет ключ, справочник и ближайшее точное написание либо нужный `categoryId`, `details.knownStages` перечисляет стадии справочника (до 50), `details.entityId` — какой справочник смотреть: `GET /v1/statuses?filter[entityId]=…`. Любое написание ключа, которое Битрикс24 читает как `STAGE_ID` (`STAGE_ID`, `stage_id`, `StageId`), проверяется так же; при нескольких написаниях в теле действует последнее, и ошибка называет его в `details.field`. Список или объект вместо названия стадии под сырым написанием ключа (`STAGE_ID`, `stage_id`…) — тоже отказ (Битрикс24 кладёт такую запись на стадию по умолчанию; под `stageId` / `statusId` такое значение раньше отклоняет проверка формы — `400 INVALID_PARAMS`): он выносится без чтения справочника, поэтому `details.knownStages` в этом случае пуст, а `details.stageId` называет форму значения («an array», «an object»). Пустая стадия (`""`, `null`) не проверяется — запись ложится на стадию по умолчанию. Раньше такой вызов отвечал `201`, а Битрикс24 молча создавал запись на стадии по умолчанию. Если справочник прочитать не удалось или он пришёл неполным, запись выполняется как прежде |
| `BATCH_LIMIT_EXCEEDED` | 400 | Запрос содержит больше 50 элементов в массивной операции (`chats`, `task-comments` и подобные) |
| `MESSAGE_REQUIRED` | 400 | `POST /v1/chats/{dialogId}/messages` без текста: поле `message` пустое и нет блока `attach`. `PATCH /v1/chats/{dialogId}/messages/{messageId}` без текста — по правилу Битрикс24 (одни пробелы, теги `[BR]`/`[br]` или NUL считаются пустым, а пустой текст удалял бы сообщение). Частая причина — текст передан под неизвестным именем поля, например `text`. Ответ перечисляет нераспознанные поля |
| `INVALID_EVENT` | 400 | Код события подписки портала не соответствует формату `^[A-Z][A-Z0-9_]+(?:\.[A-Z][A-Z0-9_]+)*$`. См. [Подписки на события портала](./infra/event-subscriptions.md) |
| `INVALID_APP_PATH` | 400 | Путь доставки `appPath` не начинается с `/` либо содержит управляющие символы. См. [Подписки на события портала](./infra/event-subscriptions.md) |
| `PLATFORM_HANDLER_UNRESOLVABLE` | 400 | Адрес обработчика указывает на технический адрес сервера приложения, а платформенный обработчик определить не удалось. Место встраивания не зарегистрировано. См. [Привязать место](./apps/placements/bind.md) |

Пустое тело с заголовком `Content-Type: application/json` принимается как `{}` на маршрутах `/v1/infra/*`, а также на **всех** маршрутах пользовательских полей: `/v1/userfields/:entity`, `/v1/userfields/:entity/types` и `/v1/userfields/:entity/:id`, те же три пути под `/v1/items/:entityTypeId/userfields`, а также короткие адреса счетов `/v1/userfields/invoices`, `/v1/userfields/invoices/types` и `/v1/userfields/invoices/:id`. Операции, которым тело не нужно — [`POST /v1/infra/servers/:id/wake`](./infra/lifecycle/wake.md), [`DELETE /v1/infra/servers/:id/access-tokens/:tokenId`](./infra/access-tokens.md) и подобные, — отвечают по существу, а не отклоняют запрос на разборе тела. Так ведут себя клиенты, которые ставят этот заголовок на любой запрос (например, axios и PowerShell `Invoke-RestMethod`).

Дальше запрос проверяет сама операция, и код отказа зависит от маршрута — берите его из таблицы выше или со страницы нужной операции. Тело, которое не разбирается как JSON, на этих маршрутах отклоняется кодом `INVALID_JSON_BODY`, то есть пустое и битое тело различаются.

Причины и порядок действий по `VALIDATION_ERROR`, `INVALID_PARAMS`, `MISSING_REQUIRED_FILTER` и `BATCH_LIMIT_EXCEEDED` — [Запрос и данные](/docs/errors/request).

### Размер тела запроса

| Код | HTTP | Когда возникает |
|-----|------|-----------------|
| `PAYLOAD_TOO_LARGE` | 413 | Тело запроса больше потолка этого маршрута |
| `INLINE_SOURCE_TOO_LARGE` | 413 | Тело со встроенным архивом или файлом больше 96 МБ на трёх маршрутах инфраструктуры — [выкладка кода](./infra/deploy/deploy.md), [загрузка файла](./infra/deploy/upload.md) и [создание сервера](./infra/servers/create.md) с полем `source` |
| `LARGE_BODY_BACKEND_BUSY` | 429 | Платформа уже обрабатывает предельный объём крупных тел. Запрос не выполнялся, повторите его через `Retry-After` секунд |

Потолок зависит от маршрута. По умолчанию — 1 МБ. Создание и обновление записей и элементов списков, файлы ботов и чатов, `note.file.add` — 40 МиБ. Загрузка на Диск — 70 МБ. Файл внутри тела едет в base64 и растёт примерно на треть, поэтому исходный файл при потолке 40 МиБ — чуть меньше 30 МиБ. Тот же код приходит от пограничного слоя на его собственном пороге. Тело под необъявленным типом содержимого — например, `text/plain` — на маршрутах сущностей, пользовательских полей, чатов, заметок, ключей и Cowork/Code отклоняется кодом `415 FST_ERR_CTP_INVALID_MEDIA_TYPE`, а пустое тело под тем же типом принимается там как `{}`. На `/v1/infra/*` и `/v1/apps`, включая публикацию исходников и места встраивания, потолок тела для непонятого типа равен одному байту, поэтому тот же запрос отвечает `413`.

Крупным считается тело больше 1 МиБ — это тот же порог, что и потолок по умолчанию, — и суммарный объём одновременно обрабатываемых крупных тел ограничен. Отказ приходит там, где потолок тела поднят: записи сущностей, запись элементов списков, файлы ботов и файлы чатов, загрузка на Диск (`POST /v1/files/upload`), файлы заметок (`POST /v1/note/documents/{documentId}/files`), а также `POST /v1/chat/completions` и `POST /v1/audio/transcriptions` вместе со своими псевдонимами под `/v1/ai/`. Когда свободного объёма нет, приходит `429 LARGE_BODY_BACKEND_BUSY` с заголовком `Retry-After: 5`. Так же отвечает запрос без заголовка `Content-Length`, если объём переваливает тот же порог уже по ходу передачи. Транскрипции — исключение: там учитывается только объявленный `Content-Length`, а загрузка без него ограничена одним потолком в 25 МБ на файл. На маршрутах AI у этого отказа конверт, совместимый с OpenAI: без поля `success` и с кодом `large_body_backend_busy` в нижнем регистре. Срок повтора берите из заголовка: поле `error.retryAfter` в теле этого отказа приходит не на всех путях.

Исключение — маршруты AI (`/v1/ai/*`, `/v1/chat/*`, `/v1/audio/*`, `/v1/models`): у них конверт ошибки, совместимый с OpenAI, и на превышении тела в `error.code` приходит служебный код фреймворка в нижнем регистре, а не `PAYLOAD_TOO_LARGE`.

Свой код и свой потолок у тела, которое несёт архив или файл внутри JSON: [выкладка кода](./infra/deploy/deploy.md) с `source.content`, [загрузка файла](./infra/deploy/upload.md) с `content` и [создание сервера](./infra/servers/create.md) с полем `source` принимают до 96 МБ тела, а сверх этого отвечают `413 INLINE_SOURCE_TOO_LARGE`. Считается именно тело: содержимое едет в base64 и тяжелее исходных байт примерно на треть, поэтому потолку соответствует около 72 МБ самого архива. Решение принимается по заголовку `Content-Length` до чтения тела, а `error.hint` называет способ отправить тот же архив другим путём. Ссылка (`source.url`, `url`) и сохранённая версия (`source.versionId`) под этот потолок не попадают — у них свои 500 МБ.

### Загрузка файлов

| Код | HTTP | Когда возникает |
|-----|------|-----------------|
| `STORAGE_FORBIDDEN_CONTENT_TYPE` | 415 | Для `PUBLIC`-объектов запрещены типы `text/html`, `application/javascript`, `application/x-javascript`, `image/svg+xml` — они опасны межсайтовым выполнением скриптов. Загружайте такой файл как `PRIVATE` |

### Предусловия подписок на события портала

| Код | HTTP | Когда возникает |
|-----|------|-----------------|
| `NOT_OAUTH_APP` | 400 | Сервер не привязан к OAuth-приложению с `application_token` — подписку на событие зарегистрировать нельзя |
| `NO_USER_TOKEN` | 400 | У приложения нет OAuth-токена — сначала авторизуйте приложение на портале |

Полное описание операций — [Подписки на события портала](./infra/event-subscriptions.md).

### Установка приложения через модуль-коннектор

| Код | HTTP | Когда возникает |
|-----|------|-----------------|
| `CONNECTOR_APP_INSTALL_FORBIDDEN` | 403 | Администратор аккаунта Битрикс24 запретил этому сотруднику устанавливать приложения. Право выдаёт администратор аккаунта, повтор запроса состояние не меняет. Подробнее — [Права на создание](/docs/access-rights) |
| `CONNECTOR_MODULE_NOT_INSTALLED` | 409 | Модуль-коннектор на аккаунте не установлен. Состояние постоянное — пока модуль не установят, повтор бессмыслен |
| `CONNECTOR_APP_INSTALL_FAILED` | 502 | Другой сбой установки на стороне модуля-коннектора. Запрос можно повторить |
| `CONNECTOR_REST_UNAVAILABLE` | 502 | Подписка или пробный период действуют, но Битрикс24 отказал в выписке парного ключа. Исходная причина — в `error.details.reason`, `error.details.retryable: true` говорит, что состояние временное |
| `CONNECTOR_PLAN_REQUIRED` | 502 | Тариф аккаунта Битрикс24 не включает Вайбкод, и предлагать нечего — коробочный аккаунт, аккаунт уже на платном тарифе, нераспознанный регион. Текст причины для человека — в `error.userMessage`. Состояние постоянное: повтор не поможет, пока тариф не сменён. Там, где доступ продаётся, тот же отказ приходит ответом `402` с кодом тарифного пейвола |

Коды приходят на [создании приложения](./apps/create.md) там, где приложение устанавливает модуль-коннектор: на коробочном аккаунте, а на облачном — когда такой выпуск для аккаунта включён. При любом из этих отказов ни приложение, ни парный ключ не создаются.

### Модуль Битрикс24 недоступен на портале

| Код | HTTP | Когда возникает |
|-----|------|-----------------|
| `BIZPROC_MODULE_NOT_ENABLED` | 409 | Бизнес-процессов на портале нет: модуль не входит в тариф либо выключен в настройках портала. Приходит в разделах [шаблонов](./entities/bizproc-templates.md), [действий](./entities/bizproc-activities.md) и [роботов](./entities/bizproc-robots.md) бизнес-процессов, а также [запущенных процессов](./automation/workflows.md). В [пакетном вызове](./batch.md) ответ остаётся `200`, а код приходит в ответе отказавшего вызова |
| `LANDING_MODULE_NOT_ENABLED` | 409 | Модуль «Сайты» недоступен на портале. Приходит при чтении [сайтов](./entities/sites.md): список, получение, поиск и агрегация |
| `LISTS_MODULE_NOT_ENABLED` | 409 | Модуль [универсальных списков](./lists.md) недоступен на портале |
| `MAIL_MODULE_NOT_ENABLED` | 409 | Модуль «Почта» или методы [почтовых ящиков](./mail/mailboxes.md) недоступны на портале |
| `TIMEMAN_MODULE_NOT_ENABLED` | 409 | На портале нет [учёта рабочего времени](./workday.md): модуль не входит в тариф либо выключен в настройках портала |

Это состояние портала, а не ошибка запроса: пока модуль на портале недоступен, повтор вернёт тот же отказ. Выключенный модуль включает администратор портала.

### Ресурс не найден

| Код | HTTP | Когда возникает |
|-----|------|-----------------|
| `ROUTE_NOT_FOUND` | 404 | Маршрута или HTTP-глагола не существует: опечатка в пути, несуществующая сущность, неподдерживаемый метод, а также операция, которой у этой сущности нет. Сверьте путь со списком в `GET /v1/guide`. Когда путь составлен из имени метода Битрикс24, ответ дополнительно называет замену — см. «Имя метода Битрикс24 вместо пути V1» ниже |
| `ENTITY_NOT_FOUND` | 404 | Запись CRM-сущности с указанным `id` не существует. Канонический код для `/v1/deals/:id`, `/v1/contacts/:id` и подобных |
| `NOT_FOUND` | 404 | Только `GET /:id`: Битрикс24 вернул `success`, но `result` пустой (применимо к нескольким смарт-методам) |
| `OPERATION_NOT_FOUND` | 404 | Операции выкладки с таким идентификатором нет, она принадлежит другому ключу либо запись уже удалена. Три случая отвечают одинаково намеренно — см. [Исход выкладки](./infra/deploy/operation-status.md) |

Доменные `*_NOT_FOUND` (`BOT_NOT_FOUND`, `SERVER_NOT_FOUND`, `AGENT_NOT_FOUND`, `APP_NOT_FOUND`, `PORTAL_NOT_FOUND`, `USER_NOT_FOUND`, `FILE_NOT_FOUND`, `SUBSCRIPTION_NOT_FOUND`) описаны на страницах соответствующих разделов.

`B24_EMBEDDING_APP_NOT_FOUND` (404) — отдельный случай: приложение есть на платформе Вайбкод, но Битрикс24 не знает его идентификатор. Условие и порядок восстановления — в группе «Права и скоупы» выше.

**Два вида 404.** Один и тот же HTTP-статус `404` означает два разных состояния — различайте их по `error.code`. `ROUTE_NOT_FOUND` — маршрута или глагола не существует, повторять запрос бессмысленно: проверьте путь по `GET /v1/guide`. `ENTITY_NOT_FOUND` и доменные коды вида `*_NOT_FOUND` — маршрут существует, не найден запрошенный объект. Оба состояния отвечают в едином конверте V1.

Маршрута не существует:

```json
{
  "success": false,
  "error": {
    "code": "ROUTE_NOT_FOUND",
    "message": "Route GET:/v1/dealz not found. Check GET /v1/guide for available endpoints and verbs."
  }
}
```

Маршрут существует, объекта нет:

```json
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Элемент не найден"
  }
}
```

**Имя метода Битрикс24 вместо пути V1.** Пути API Вайбкод не повторяют имена методов Битрикс24, поэтому запрос вида `GET /v1/crm.deal.list` отвечает `404 ROUTE_NOT_FOUND` и метод портала не вызывает. Для разобранных случаев ответ вдобавок называет верный маршрут в `error.details`.

| Поле `error.details` | Тип | Описание |
|---|-----|----------|
| `reason` | string | `BITRIX_METHOD_AS_PATH` — путь составлен из имени метода Битрикс24 |
| `bitrixMethod` | string | Имя метода, распознанное в пути |
| `suggestedEndpoint` | object | Маршрут V1, который решает ту же задачу: `method` и `path` |
| `guide` | object | Указатель на справочник маршрутов: `method` и `path` (`GET /v1/guide`) |

Замена называется для четырёх методов: `catalog.product.list` → [GET /v1/catalog-products](./entities/catalog-products.md), `crm.deal.list` → [GET /v1/deals](./entities/deals.md), `crm.user.list` → [GET /v1/users](./entities/users.md), `crm.deal.search` → [POST /v1/deals/search](./entities/deals/search.md). На остальных путях приходит `ROUTE_NOT_FOUND` без `details`, и маршрут нужно найти через [`GET /v1/guide`](./keys-auth/guide.md).

```json
{
  "success": false,
  "error": {
    "code": "ROUTE_NOT_FOUND",
    "message": "Route GET:/v1/crm.deal.list not found. Bitrix24 method names are not V1 API paths; use GET /v1/deals instead. Check GET /v1/guide for required parameters and other endpoints.",
    "details": {
      "reason": "BITRIX_METHOD_AS_PATH",
      "bitrixMethod": "crm.deal.list",
      "suggestedEndpoint": { "method": "GET", "path": "/v1/deals" },
      "guide": { "method": "GET", "path": "/v1/guide" }
    }
  }
}
```

Повторите запрос по `suggestedEndpoint`, а состав параметров возьмите из `guide`: набор фильтров и полей у маршрута V1 свой, а не унаследованный от метода портала.

Причины и порядок действий по `ENTITY_NOT_FOUND` — [Запрос и данные](/docs/errors/request).

### Конфликты состояния

| Код | HTTP | Когда возникает |
|-----|------|-----------------|
| `CONFLICT` | 409 | Текущее состояние ресурса несовместимо с запросом |
| `ALREADY_EXISTS` | 409 | Запись с такими ключевыми полями уже существует |
| `CURRENCY_MISMATCH` | 409 | Валюта оплаты не совпадает с валютой её заказа. Проверяется при создании оплаты. При изменении поле не проверяется — в теле запроса нет заказа. Битрикс24 хранит оплату в валюте заказа и присланную не применяет. Чтобы унаследовать валюту, не передавайте поле. См. [Создать оплату](./entities/payments/create.md) |
| `B24_USER_DELETED` | 409 | Сотрудник Битрикс24, которому принадлежит ключ, больше не активен на аккаунте — выписать ключ на него нельзя. Приходит везде, где у ключа появляется владелец: [создание приложения](./apps/create.md), [выдача проектного ключа](./cowork/deploy-key.md), а также выпуск и перевыпуск ключа менеджмент-ключом ([менеджмент-ключи](./management-keys.md)). Состояние постоянное, помогает только восстановление сотрудника на аккаунте |
| `KEY_ROTATION_RECOVERY_REQUIRED` | 409 | Замена ключа не завершена: его перевыпуск закончился ответом `500` или ещё не закончился. Приходит на перевыпуске и удалении такого ключа и на выпуске им [токена доступа](./infra/access-tokens/create.md). Порядок действий — [Менеджмент-ключи](./management-keys.md) |
| `APPLICATION_KEY_RECOVERY_REQUIRED` | 409 | Ключ с незавершённой заменой не привязывается к серверу или приложению. Приходит в том числе на [создании сервера](./infra/servers/create.md), когда не завершена замена ключа, которым сделан запрос, и на замене ключа приложения Коворка, когда в незавершённой замене участвует ключ, привязанный к этому приложению. Новое значение `Idempotency-Key` отказ не снимает |
| `AGENT_WRITE_ALREADY_EXECUTED` | 409 | [AI-агент](./agents.md) повторно отправил `DELETE` на тот же адрес в течение 30 секунд после первого вызова. Повтор не выполняется. В `error.firstStatus` — код успешного ответа первого удаления или `null`, если оно ещё выполняется. В `error.firstExecutedAt` — время первого вызова. Если первое удаление не удалось, повтор проходит обычным порядком. Создание и изменение так не проверяются, запросы других ключей отказ не затрагивает |
| `EVENT_BOUND_ELSEWHERE` | 409 | Событие портала уже привязано к другому серверу того же OAuth-приложения. См. [Подписки на события портала](./infra/event-subscriptions.md) |
| `CATALOG_ALREADY_PUBLISHED` | 409 | У сервера уже есть карточка в каталоге приложений Битрикс24. См. [Опубликовать в каталоге](./infra/servers/b24-catalog-publish.md) |
| `CATALOG_DELETE_PENDING` | 409 | По карточке в каталоге уже поставлено удаление — публикация в этом состоянии недоступна |
| `OAUTH_CLIENT_ID_IN_USE` | 409 | `POST /v1/apps/:id/relink-oauth`: указанный `bitrixClientId` уже привязан к другому приложению. Один `client_id` — одно приложение |
| `OPERATION_OUTCOME_EXPIRED` | 410 | Операция выкладки ваша и она точно была, но её исход больше не хранится (срок — 7 суток). См. [Исход выкладки](./infra/deploy/operation-status.md) |

### Биллинг и тариф

Возникают на эндпоинтах создания и пробуждения инфраструктуры (серверы, агенты, управляемые боты). Ответ содержит `userMessage` на русском языке для показа в интерфейсе клиента.

| Код | HTTP | Когда возникает |
|-----|------|-----------------|
| `BILLING_EXHAUSTED` | 402 | Баланс ушёл в красную зону, аккаунт заморожен. Нужно пополнение баланса |
| `ACCOUNT_FROZEN` | 402 | Платёжный аккаунт заморожен за отрицательный баланс. Отказ приходит на вызовах, которые оплачиваются балансом Вайбкод. Полный состав — в блоке «Что закрывает заморозка счёта» ниже |
| `COMMERCIAL_PLAN_REQUIRED` | 402 | Платформа не нашла запись портала, к которому привязан ключ, поэтому не может проверить доступ. Приходит на [создании сервера](./infra/servers/create.md) |
| `OPEN_MODE_REQUIRES_COMMERCIAL` | 402 | Переход сервера в OPEN или включение `allowOpenMode` требует полного доступа сейчас: платной подписки в подписочной модели или подходящего тарифа Битрикс24 в тарифной модели. Прежние платежи и пробный доступ отказ не снимают; подсказка — в `userMessage`, ссылка — в `details.upgradeUrl` |
| `MARKETPLACE_REQUIRED` | 402 | На портале нет активной подписки BitrixGPT + Маркетплейс — оформите её, чтобы открыть создание серверов, деплой и выписку ключей. Выписка ключей закрывает и [создание приложения](/docs/apps/create): парный ключ выписывается там же. На пробуждении этот код получает только [galaxy-приложение](./infra/galaxy.md). Приходит только там, где доступ к платформе открывает подписка. Где его открывает тариф Битрикс24, отказ приходит кодами `BY_PAID_ONLY`, `KZ_PAID_ONLY` и `UZ_PAID_ONLY` — их таблица лежит в разделе «Инфраструктура», в «Ошибках проверки доступа и биллинга» |
| `SELFHOSTED_NOT_AVAILABLE` | 402 | Коробочный Битрикс24 пока не доступен на этой установке — доступ открывается постепенно. Серверы и данные портала сохраняются, ничего не удаляется. Покупкой тарифа отказ не снимается: адрес обращения — поддержка (`details.upgradeUrl` содержит `mailto:`) |
| `B24_PAID_TARIFF_REQUIRED` | 402 | Тариф Битрикс24 на портале бесплатный, а на таком тарифе Битрикс24 закрывает REST при любом состоянии подписки BitrixGPT + Маркетплейс. Ответ несёт `userMessage` и не ведёт к оформлению: помогает только переход портала на любой платный тариф Битрикс24, повтор запроса состояние не меняет. Приходит на выписке ключа портала и на установке приложения. Тариф «Демо» не затронут — на нём REST работает |
| `TRIAL_PORTAL_LIMIT` | 402 | На пробном периоде превышен общий лимит серверов на портал |
| `APPLICATION_REUSE_CONFLICT` | 409 | Пока платформа подбирала существующий сервер для повторного использования, привязку сервера к приложению изменил параллельный запрос. `retryable: true`, повторите запрос создания |
| `PLAN_NOT_ALLOWED_ON_TRIAL` | 402 | Запрошенный план сервера/агента недоступен на пробном периоде |
| `GALAXY_NOT_ON_TRIAL` | 402 | Хост Galaxy нельзя создать на пробном доступе. Получите полный доступ по модели региона; для пробного развёртывания используйте отдельный сервер с планом из `capabilities.servers.create.limits.allowedPlans` ответа `GET /v1/me` в пределах оставшейся квоты. Контейнер `GALAXY_APP` на существующем подходящем хосте этим отказом не запрещён |
| `SERVER_WAKE_BLOCKED` | 403 | Пробуждение сервера заблокировано по небиллинговой причине — например, закончился доступ к платформе |
| `B24_MARKET_SUBSCRIPTION_REQUIRED` | 403 | На аккаунте нет активной подписки BitrixGPT + Маркетплейс. Приходит на [привязке места встраивания](./apps/placements/bind.md), на установке приложения, а также на выписке и перевыпуске ключа портала — в том числе на коробочном портале, где ключ выдаёт модуль-коннектор. На облачном аккаунте с прочитанным бесплатным тарифом Битрикс24 вместо него приходит `B24_PAID_TARIFF_REQUIRED`. Коробочный аккаунт эта подмена не затрагивает |
| `B24_MARKET_TRIAL_USED` | 403 | Пробный период подписки BitrixGPT + Маркетплейс уже использован — привязка места встраивания, установка приложения, выписка и перевыпуск ключа портала требуют платной подписки. На облачном аккаунте с прочитанным бесплатным тарифом Битрикс24 вместо него приходит `B24_PAID_TARIFF_REQUIRED`. Коробочный аккаунт эта подмена не затрагивает |
| `INT_TARIFF_REQUIRED` | 403 | Аккаунт работает по тарифной модели доступа, при этом [привязка места встраивания](./apps/placements/bind.md), установка приложения, выписка и перевыпуск ключа портала требуют коммерческого тарифа Битрикс24 |
| `PORTAL_TARIFF_UNREADABLE` | 403 | Тариф аккаунта прочитать не удалось, поэтому какой именно тариф нужен, ответ не называет: поле `details.requiredTariffs` пустое, а кнопка ведёт в поддержку. Покупка тарифа отказ не снимает |
| `PORTAL_SUBSCRIPTION_UNREADABLE` | 403 | Состояние подписки аккаунта прочитать не удалось: ключу разработчика не хватает прав на чтение лицензии, поэтому платформа не знает, есть подписка или нет. Поле `details.requiredTariffs` пустое, покупка отказ не снимает — приложение нужно переподключить под главным администратором аккаунта, чтобы ключ получил нужные права |

**Что закрывает заморозка счёта.** Отказ `402 ACCOUNT_FROZEN` приходит на вызовах, которые оплачиваются балансом Вайбкод: инфраструктура `/v1/infra/...`, хранилище `/v1/storage/...`, [поиск](./search/run.md) и [глубокий поиск](./search/research.md), расход AI сверх месячной квоты тарифа портала, депо исходников приложения, вложения обращений и [правка обращения](./feedback/update.md), а также [выписка проектного ключа](./cowork/deploy-key.md), [создание приложения](./apps/create.md) и [создание приложения из Cowork/Code](./cowork/applications-create.md), [активация купона](./cowork/coupon-redeem.md), [сброс лимитов по праву акции](./cowork/limits-reset.md) и [подключение демо Маркетплейса](./cowork/activate-market-trial.md).

Вызовы, за которые баланс не платит, под заморозкой продолжают работать: обращения к своему Битрикс24 через маршруты сущностей и [пакетный вызов](./batch.md), AI в пределах месячной квоты тарифа портала, оплаченный период подписки Cowork/Code, [список моделей](./ai/models/list.md), самоописание [`GET /v1/me`](./keys-auth/me.md), [справочник](./keys-auth/guide.md), спека `GET /v1/openapi.json`, переписка по обращениям — создание, список, чтение одного обращения и комментарий к нему — и отзыв своего ключа Cowork/Code.

У всех перечисленных семейств, кроме AI, отказ выносится до валидации запроса, поэтому `400` и `404` на закрытом заморозкой вызове не приходят. У AI-маршрутов решение принимает сам обработчик, уже разобрав параметры: запрос с неверным полем ответит `400` раньше, чем дойдёт до проверки заморозки.

**Важно:** сужение отказа раскатывается по порталам постепенно. Пока оно не дошло до вашего портала, заморозка отвечает `402 ACCOUNT_FROZEN` почти на любой вызов V1, включая чтения по сущностям и пакетный вызов. Открытыми в этом состоянии остаются самоописание, справочник, спека, те же четыре вызова переписки по обращениям и отзыв своего ключа Cowork/Code.

Причины и порядок действий по `BILLING_EXHAUSTED`, `COMMERCIAL_PLAN_REQUIRED`, `B24_MARKET_SUBSCRIPTION_REQUIRED`, `B24_MARKET_TRIAL_USED` и `INT_TARIFF_REQUIRED` — [Биллинг, тариф и подписка](/docs/errors/billing).

### Ограничение частоты

| Код | HTTP | Когда возникает |
|-----|------|-----------------|
| `RATE_LIMITED` | 429 | Битрикс24 ограничил частоту запросов или превышен внутренний лимит. У одиночного отказа срок повтора приходит заголовком `Retry-After` (секунды), поля `retryAfter` в теле нет. У сформированной платформой подошибки пакета срок приходит полем `retryAfter` внутри ответа `200`, без отдельного заголовка для подвызова |
| `CALLER_RATE_LIMITED` | 429 | Исчерпан общий поминутный лимит запросов. Платформенные потолки: 600 на API-ключ, 1200 на все ключи одного владельца; опрос событий бота считается отдельными счётчиками — 120 на бота, 600 на ключ и 1200 на владельца. Потолки делятся между репликами бэкенда, поэтому отказ может прийти раньше названных чисел, а эффективное число в заголовке не публикуется ([подробнее](/docs/errors/limits)). Заголовок `X-RateLimit-Scope` называет счётчик (`key`, `user`, `bot`), `Retry-After` — секунды до конца минутного окна. Поля `retryAfter` в теле нет |
| `ERROR_LOOP_DETECTED` | 429 | Блокировка на стороне Вайбкод: один и тот же запрос повторяется с одинаковой ошибкой. Сигнал о баге в коде клиента. Для пробы нужны N запросов и растущая пауза; успешный вызов снимает блок |
| `OPERATION_TIME_LIMIT` | 429 | Битрикс24 приостановил ЭТОТ метод для ВАШЕГО ключа примерно на 5 минут: метод исчерпал бюджет рабочего времени. В ответе `scope: "apiKey"`, `retryAfter` и заголовок `Retry-After`. Остальные методы и другие ключи портала работают |
| `TIMEOUT_QUARANTINE` | 429 | Блокировка на стороне Вайбкод: метод несколько раз подряд не ответил порталу за отведённое вызову время, и пара «портал + метод» поставлена на паузу. В ответе `scope: "portal"`, `retryAfter` и заголовок `Retry-After`. Пауза общая для ВСЕХ ключей портала и снимается автоматически |

Причины и порядок действий по этой группе — [Лимиты, очереди и паузы](/docs/errors/limits).

### Бэкенд и сторонние сервисы

| Код | HTTP | Когда возникает |
|-----|------|-----------------|
| `BITRIX_ERROR` | 422 | Битрикс24 вернул бизнес-ошибку, не подпадающую под более узкие категории (`ACCESS_DENIED`, `NOT_FOUND`, `INVALID_PARAMS`) |
| `AGGREGATION_LIMIT_EXCEEDED` | 422 | [Агрегация](./entity-api.md#агрегация-post-потолок-5000-записей) отказалась отвечать: выборка шире 5000 записей, оценённая стоимость вызова превысила безопасный бюджет, страница записей не догрузилась — либо (для дел без сужающего фильтра) Битрикс24 не ответил за отведённое на вызов время. `message` говорит, какой именно случай. Заголовка `Retry-After` нет: отказ не временный |
| `METHOD_NOT_YET_AVAILABLE` | 422 | Метод выходит в обновлении Битрикс24 и на этот портал ещё не приехал. Ответ содержит поле `error.release` с идентификатором обновления, например `imopenlines 26.700.0`. Это признак раскатки, а не ошибка вызова — [подробнее](/docs/errors/platform#method_not_yet_available-422) |
| `STAGE_NOT_APPLIED` | 422 | Битрикс24 принял запись, но не применил стадию или воронку: присланное значение не из справочника. Запись уже создана или изменена — фактическое состояние приходит в `data` ответа. Тот же вердикт выносят пакетные двери и импорт, только внутри `200`: элемент `POST /v1/{entity}/batch` и строка `POST /v1/{entity}/import` получают `success: false`, этот код в `error` и сохраняют `id`; подвызов `POST /v1/batch` уходит в `data.errors.<id>` с записью в `data` этой ошибки. При одиночном создании этот код не выносится: там стадия проверяется по справочнику ДО записи и отказ приходит кодом `UNKNOWN_STAGE` (сверять запись после создания нельзя — там работает автоматизация портала, и робот «при создании» дал бы ложный отказ; импорт правила автоматизации не запускает) |
| `AMOUNT_NOT_APPLIED` | 422 | Запрос ЯВНО просил ручной режим суммы (`isManualOpportunity: true`) у элемента смарт-процесса, Битрикс24 принял запись, но флаг не сохранил. Обычная причина — у типа выключена товарная часть (`isLinkWithProductsEnabled: false`): сумма и флаг хранятся только у типов с ней. Ручной режим распознаётся во всех написаниях, которые принимает платформа: `true`, `"true"`, `"Y"`, `"yes"`, `"1"`. Сумма, если её присылали, перечисляется в отказе вместе с флагом; сумма БЕЗ флага не проверяется — по ответу её не отличить от законного пересчёта по товарным позициям. Запись уже создана или изменена — её фактическое состояние приходит в `data` ответа, а неприменённые поля перечислены в `error.details.unappliedFields`. Раньше такой вызов отвечал `201`/`200` и сумма пропадала молча. Тот же вердикт выносят пакетные двери и импорт, только внутри `200`: элемент `POST /v1/items/{entityTypeId}/batch` и строка `POST /v1/items/{entityTypeId}/import` получают `success: false`, этот код в `error` и сохраняют `id`; подвызов `POST /v1/batch` уходит в `data.errors.<id>` с записью в `data` этой ошибки |
| `REST_REGISTRATION_FAILED` | 400 | Битрикс24 отказал в регистрации приложения или входящего вебхука и причину не назвал. Приходит на [создании приложения](/docs/apps/create) и на выписке ключа портала. Ответ несёт `error.details.incidentCode` — шестисимвольный код обращения, по которому поддержка находит запись в журнале. Назовите этот код в обращении |
| `BITRIX_UNAVAILABLE` | 502 | Битрикс24 вернул 5xx, не ответил вовремя или связь с порталом оборвалась до полного ответа |
| `BIND_FAILED` | 502 | Битрикс24 отклонил регистрацию события (`event.bind`) — например, портал не на коммерческом тарифе. См. [Подписки на события портала](./infra/event-subscriptions.md) |
| `WINDOWED_SEARCH_FAILED` | — | Больше не возвращается: при полном отказе авто-окон `/search` возвращается реальный код Битрикс24 — `UNKNOWN_FILTER_FIELD` / `INVALID_PARAMS` / `BITRIX_ACCESS_DENIED` / `RATE_LIMITED` / `BITRIX_UNAVAILABLE` / `BITRIX_TIMEOUT` (503) / `BITRIX_ERROR` (422), как для узкого диапазона |
| `QUEUE_OVERFLOW` | 429 | Очередь портала переполнена: слишком много одновременных вызовов Битрикс24. Отклоняется мгновенно, `Retry-After` в заголовке |
| `QUEUE_TIMEOUT` | 429 | Очередь портала перегружена: больше 80 секунд ожидания на стороне Вайбкод. Запрос не был отправлен в Битрикс24 — безопасно повторить |
| `BITRIX_TIMEOUT` | 503 | Битрикс24 принял запрос, но не ответил за 60 секунд — исход неизвестен. Для операций записи: сначала перечитайте сущность, изменение могло примениться |
| `POOL_EXHAUSTED` | 503 | Сервис временно перегружен — исчерпан пул соединений с базой данных. В ответе `retryAfter` и заголовок `Retry-After`. Для записи исход неизвестен: перед повтором перечитайте состояние |
| `DB_TRANSIENT` | 503 | Транзакция в базе данных закрылась или истекла. В ответе `retryAfter` и заголовок `Retry-After`. Откат локальной транзакции не откатывает уже совершённый вызов Битрикс24, поэтому для записи сначала перечитайте состояние |
| `SERVICE_UNAVAILABLE` | 503 | Граница платформы не смогла передать запрос бэкенду (например, в момент редеплоя) — либо не дождалась ответа. В ответе `retryAfter` и заголовок `Retry-After`. Если запрос мог быть выполнен (истёк таймаут ожидания ответа), для не-идемпотентных операций перед повтором сверьте состояние сущности |
| `INTERNAL_ERROR` | 500 | Непредвиденная ошибка бэкенда Вайбкод |
| `PLACEMENT_UNBIND_FAILED` | 502 | Аккаунт не подтвердил снятие мест встраивания. [Публикация](./apps/publish.md) и [изменение приложения](./apps/update.md) при этом не применяются, коды приходят в `error.placements`. Возвращается только на аккаунтах, где включена проверка снятия |
| `NETWORK_DEVKEY_REQUIRED` | 503 | Ключ разработчика для автора приложения ещё не выдан — [привязка места встраивания](./apps/placements/bind.md) временно недоступна. На аккаунтах с включённой проверкой снятия тем же кодом отвечают [публикация](./apps/publish.md) и [изменение приложения](./apps/update.md) |

Причины и порядок действий по `BITRIX_ERROR`, `METHOD_NOT_YET_AVAILABLE`, `BITRIX_UNAVAILABLE`, `BITRIX_TIMEOUT` и `INTERNAL_ERROR` — [Битрикс24 и платформа](/docs/errors/platform). По `QUEUE_OVERFLOW` и `QUEUE_TIMEOUT` — [Лимиты, очереди и паузы](/docs/errors/limits). Доставка целевого вызова и безопасность повтора чтения или записи собраны отдельно на странице [Что безопасно повторять](/docs/errors/retry-safety).

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

- [Быстрый старт](./quickstart.md)
- [Ключи и авторизация](./keys-auth.md)
- [Лимиты и оптимизация](./optimization.md)
- [Что безопасно повторять](/docs/errors/retry-safety)
- [Batch](./batch.md)
- [CLI и cURL](./cli.md)
- [MCP для AI](./mcp.md)