# Биллинг, тариф и подписка

Подробный разбор кодов, которыми API Вайбкод закрывает операцию из-за баланса, тарифа Битрикс24 или условий подписки аккаунта.

Сводная таблица всех кодов API Вайбкод — [Коды ошибок](/docs/errors).

## `BILLING_EXHAUSTED` (402)

Платёжный аккаунт ушёл в красную зону: баланс отрицательный, льготный период исчерпан, средств на часовую оплату серверов и агентов нет. Запросы на создание и пробуждение инфраструктуры блокируются до пополнения.

```json
{
  "success": false,
  "error": {
    "code": "BILLING_EXHAUSTED",
    "message": "Balance depleted",
    "userMessage": "Баланс VibeCode исчерпан. Пополните счёт, чтобы возобновить создание серверов.",
    "hint": "If user says they just upgraded, call GET /v1/me?refresh=tariff to force tariff recheck."
  }
}
```

**Решение:**
- Пополнить баланс на странице `/billing/topup`.
- После пополнения перечитать состояние аккаунта — `GET /v1/me?refresh=tariff`.

---

## `COMMERCIAL_PLAN_REQUIRED` (402)

Создание серверов и агентов недоступно на бесплатном тарифе Битрикс24 после окончания пробного периода.

```json
{
  "success": false,
  "error": {
    "code": "COMMERCIAL_PLAN_REQUIRED",
    "message": "Commercial Bitrix24 tariff required for server creation",
    "userMessage": "Серверы VibeCode доступны на коммерческих тарифах Битрикс24. Оформите подписку: https://www.bitrix24.ru/prices/",
    "hint": "If user says they just upgraded, call GET /v1/me?refresh=tariff to force tariff recheck."
  }
}
```

**Решение:**
- Обновить тариф Битрикс24 до коммерческого.
- После обновления перечитать состояние аккаунта — `GET /v1/me?refresh=tariff`.

---

## `TRIAL_EXPIRED` (402)

14-дневный пробный период завершился, тариф остался бесплатным.

```json
{
  "success": false,
  "error": {
    "code": "TRIAL_EXPIRED",
    "message": "Trial period ended",
    "userMessage": "Триал VibeCode завершился. Оформите коммерческий тариф Битрикс24 для продолжения: https://www.bitrix24.ru/prices/"
  }
}
```

**Решение:**
- Перейти на коммерческий тариф Битрикс24.
- Обновить статус через `GET /v1/me?refresh=tariff`.

---

## Отказы по подписке и тарифу (403)

Три кода одного класса: доступ к операции закрыт условиями подписки или тарифа аккаунта, а не правами ключа. Приходят на [установке приложения](/docs/apps/create) и на [привязке места встраивания](/docs/apps/placements/bind) — в том числе на коробочном аккаунте, где ключ выдаёт модуль-коннектор.

| Код | Когда приходит | `error.details.upgradeUrl` |
|-----|----------------|----------------------------|
| `B24_MARKET_SUBSCRIPTION_REQUIRED` | На аккаунте нет активной подписки BitrixGPT + Маркетплейс | Передаётся для гейтов создания; не передаётся при парковке существующего бота |
| `B24_MARKET_TRIAL_USED` | Пробный период подписки уже использован — нужна платная | передаётся |
| `INT_TARIFF_REQUIRED` | Аккаунт получает доступ по тарифу Битрикс24, а не по подписке: нужен коммерческий тариф. Приходит вместо двух кодов выше, а также когда модель доступа аккаунта определить не удалось | не передаётся |

```json
{
  "success": false,
  "error": {
    "code": "INT_TARIFF_REQUIRED",
    "message": "Paid Bitrix24 plan required (international region)",
    "userMessage": "Для доступа нужен платный тариф Битрикс24."
  }
}
```

**Решение:**
- Отказ окончательный — повторять запрос бессмысленно. Пока условие доступа не изменилось на аккаунте, тот же вызов будет отклоняться.
- Если пришёл `error.details.upgradeUrl` — это готовый адрес страницы оформления на самом аккаунте. Ведите пользователя по нему, а не собирайте адрес сами.
- Если `upgradeUrl` не пришёл, на установке приложения и привязке места встраивания оформлять нечего: у аккаунта тарифная модель доступа, и нужен коммерческий тариф Битрикс24.
- Различайте эти коды в клиенте по `error.code`, а не по тексту: у трёх отказов разные действия пользователя.

**Парковка существующего бота.** Если `B24_MARKET_SUBSCRIPTION_REQUIRED` приходит с маршрута
`/v1/bots/:botId/*`, ответ несёт HTTP `403`, `Retry-After: 3600`,
`error.details.retryable:false` и `retryAfterSeconds:3600`. Остановите цикл опроса, а не повторяйте
запрос каждый час; `upgradeUrl`
намеренно нет. После продления вызовите `GET /v1/me?refresh=tariff`: свежая положительная проверка
автоматически снимет парковку со всех ботов аккаунта, после чего polling можно запустить снова.

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

- [Коды ошибок](/docs/errors)
- [Авторизация, ключи и права](/docs/errors/auth)
- [Создать приложение](/docs/apps/create)
- [Привязать место встраивания](/docs/apps/placements/bind)
- [Создать сервер](/docs/infra/servers/create)
- [Повторы и обработка ошибок в коде](/docs/errors/handling)