Для AI-агентов: markdown этой страницы — /docs-content/errors/billing.md индекс документации — /llms.txt

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

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

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

`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)

Три кода одного класса: доступ к операции закрыт условиями подписки или тарифа аккаунта, а не правами ключа. Приходят на установке приложения и на привязке места встраивания — в том числе на коробочном аккаунте, где ключ выдаёт модуль-коннектор.

Код Когда приходит 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 можно запустить снова.

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