# Billing and plans

A detailed breakdown of the codes the Vibecode API returns when it rejects an operation because of the account balance or its Bitrix24 plan.

A summary table of all Vibecode API codes — [Error codes](/docs/errors).

## `BILLING_EXHAUSTED` (402)

The billing account has gone into the red: the balance is negative, the grace period is used up, and there are no funds to cover the hourly charges for servers and agents. Requests that create or wake infrastructure are blocked until the account is topped up.

```json
{
  "success": false,
  "error": {
    "code": "BILLING_EXHAUSTED",
    "message": "Balance depleted",
    "userMessage": "Your Vibecode balance is empty. Top up to resume creating servers.",
    "hint": "If user says they just upgraded, call GET /v1/me?refresh=tariff to force tariff recheck."
  }
}
```

**Solution:**
- Top up the balance on the `/billing/topup` page.
- After the top-up, re-read the account state — `GET /v1/me?refresh=tariff`.

---

## `COMMERCIAL_PLAN_REQUIRED` (402)

Creating servers and agents is unavailable on a free Bitrix24 plan once the trial period is over.

```json
{
  "success": false,
  "error": {
    "code": "COMMERCIAL_PLAN_REQUIRED",
    "message": "Commercial Bitrix24 tariff required for server creation",
    "userMessage": "Vibecode servers require a commercial Bitrix24 plan. Get a subscription: https://www.bitrix24.com/prices/",
    "hint": "If user says they just upgraded, call GET /v1/me?refresh=tariff to force tariff recheck."
  }
}
```

**Solution:**
- Upgrade the Bitrix24 plan to a commercial one.
- After the upgrade, re-read the account state — `GET /v1/me?refresh=tariff`.

---

## `TRIAL_EXPIRED` (402)

The trial period has ended and the plan is still free.

```json
{
  "success": false,
  "error": {
    "code": "TRIAL_EXPIRED",
    "message": "Trial period ended",
    "userMessage": "Your Vibecode trial has ended. Switch to a commercial Bitrix24 plan to continue: https://www.bitrix24.com/prices/"
  }
}
```

**Solution:**
- Switch to a commercial Bitrix24 plan.
- Refresh the status with `GET /v1/me?refresh=tariff`.

---

## Plan rejections (403)

Access to the operation is denied by the account's Bitrix24 plan, not by the key permissions. The rejection arrives on [application installation](/docs/apps/create) and on [placement binding](/docs/apps/placements/bind) — including on a self-hosted account, where the key is issued by the connector module.

| Code | When it arrives | `error.details.upgradeUrl` |
|-----|----------------|----------------------------|
| `INT_TARIFF_REQUIRED` | The account's access is governed by its Bitrix24 plan, and that plan is not a commercial one. The same code arrives when the account's access model could not be determined | not provided |

```json
{
  "success": false,
  "error": {
    "code": "INT_TARIFF_REQUIRED",
    "message": "Paid Bitrix24 plan required (international region)",
    "userMessage": "A paid Bitrix24 plan is required for access."
  }
}
```

**Solution:**
- The rejection is final — repeating the request is pointless. Until the access condition changes on the account, the same call will keep being rejected.
- The field `error.details.upgradeUrl` does not arrive with this code, so there is no ready-made upgrade page to send the user to: the account has a plan-based access model and a commercial Bitrix24 plan is required.
- Branch in the client by `error.code`, not by the message text.

**Existing-bot access on `.com`.** The international instance uses the Bitrix24 plan model. After a
plan upgrade, call `GET /v1/me?refresh=tariff` to refresh access state before restarting plan-gated
work.

## See also

- [Error codes](/docs/errors)
- [Authorization, keys and permissions](/docs/errors/auth)
- [Create an application](/docs/apps/create)
- [Bind a placement](/docs/apps/placements/bind)
- [Create a server](/docs/infra/servers/create)
- [Retries and error handling in code](/docs/errors/handling)