---
title: "Токены, квоты, LMC и PAYG"
url: https://lumean.app/developers/docs/guide/billing
locale: ru
description: "Как оплачивается заказ — квота подписки, доплата с баланса и ответы 402."
updated: 2026-10-18
sources: [post-orders, post-orders-order-retry, get-subscriptions, get-usage, get-usage-service, get-wallets]
errors: ["402", payg-topup-required, quote-mismatch, insufficient-balance, insufficient-allowance]
spec_version: 1.0.0
---

# Токены, квоты, LMC и PAYG

Заказ оплачивается в токенах. Сначала токены списываются из квоты подписки. Если квоты не хватает,
недостающая часть списывается с баланса в LMC.

| Величина | Что это | Где видно |
| --- | --- | --- |
| Токен | единица объёма работы сервиса, а не деньги | `total_tokens` и `tokens_spent` в заказе, `summary.total_price_units` в превью |
| Квота подписки | запас токенов тарифа на расчётный период | `GET /subscriptions` → `items[].tokens_remaining` |
| LMC | внутренняя валюта баланса | `price_formatted` в заказе, [`GET /wallets`](/developers/docs/api/get-wallets) |

## Стоимость до заказа

```bash
curl -s -X POST "$BASE/orders/chunks/preview" -H "X-API-KEY: $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "template_id": "<UUID>", "input_text": "…" }'
```

`summary.total_price_units` — столько токенов спишет `POST /orders` за тот же текст.
`summary.cost_lmc` — та же стоимость в LMC; если её не удалось посчитать, поля в ответе нет.
Превью бесплатно и заказа не создаёт.

Остаток квоты показывает `GET /subscriptions`:

### GET /subscriptions

Подписки владельца ключа

Справочник: https://lumean.app/developers/docs/api/get-subscriptions

В ответе только действующие подписки. Остаток — в `items[].token_allowance`, `tokens_used` и
`tokens_remaining`.

### GET /usage

Лимиты использования

Справочник: https://lumean.app/developers/docs/api/get-usage

`GET /usage` перечисляет лимиты подписки: `limit_type`, `limit_value`, `used`, `remaining`,
`period_end`, `resets_in`. По одному сервису — [`GET /usage/{service}`](/developers/docs/api/get-usage-service),
где `{service}` — числовой `service_id` из ответа `GET /usage`.

Баланс в LMC возвращает [`GET /wallets`](/developers/docs/api/get-wallets) с тем же правом `billing.read`, движения средств — [`GET /ledger-transactions`](/developers/docs/api/get-ledger-transactions).

## Когда квоты не хватает

```json
{
  "data": {
    "tokens_from_quota": 1200,
    "tokens_from_payg": 300,
    "tokens_spent": 1500
  }
}
```

Недостающая часть списывается с баланса автоматически, и заказ создаётся сразу. Сколько покрыла
квота и сколько оплачено с баланса, видно в `tokens_from_quota` и `tokens_from_payg`.

У каждого сервиса своя настройка доплаты сверх квоты. Если для сервиса она закрыта, вместо списания
придёт `402` `insufficient_allowance`.

Когда оплатить заказ нельзя, он не создаётся и ничего не списывается:

| Ответ | Что случилось | Что делать |
| --- | --- | --- |
| `402` `insufficient_balance` | на балансе не хватает LMC на доплату | пополнить баланс в кабинете или сократить заказ |
| `402` `insufficient_allowance` | квота закончилась, а оплата сверх квоты для этого сервиса недоступна | дождаться новой квоты, сменить тариф или сократить заказ |
| `403` `no_subscription` | сервис работает только по подписке | оформить подписку |
| `403` `entitlement_missing` | тариф не открывает этот сервис | сменить тариф |

Так же оплачиваются `POST /orders/{order}/retry` и перегенерация чанка. `429` с
`reason: limit_exceeded` — это лимит подписки, а не оплата: см.
[Лимиты и код 429](/developers/docs/guide/limits).

### 402 — 402 — требуется оплата

| Что произошло | Что делать |
| --- | --- |
| Заказ не создан, деньги не списаны. Код приходит на `POST /orders` и `POST /orders/{order}/retry`: оба запроса оплачиваются одинаково. Повтор и перегенерация чанка тоже отвечают `402`, когда нечем оплатить доплату: `insufficient_balance`, `insufficient_allowance`, а у повтора ещё `insufficient_funds` (в заблокированном остатке заказа не хватает средств). Причину называет поле `reason`. | Ветвитесь по `reason`, а не по `message`: текст сообщения может измениться без предупреждения. При `insufficient_balance` пополните баланс. При `insufficient_allowance` дождитесь новой квоты или смените тариф. До этого тот же запрос будет возвращать тот же 402. |

`Retry-After`: нет. Разбор: https://lumean.app/developers/docs/errors/402

## Режим явного подтверждения доплаты

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

```json
{
  "success": false,
  "message": "…",
  "reason": "payg_topup_required",
  "shortfall_tokens": 300,
  "shortfall_lmc": 3.6,
  "shortfall_lmc_minor": 360000000,
  "quote_token": "q_9f8b2c1a4d3e",
  "expires_at": "2026-10-18T12:01:00+00:00"
}
```

Чтобы согласиться, повторите тот же запрос с `confirm_payg_topup: true` и `quote_token` из ответа:

```bash
curl -s -X POST "$BASE/orders" -H "X-API-KEY: $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "template_id": "<UUID>", "input_text": "…",
        "confirm_payg_topup": true, "quote_token": "q_9f8b2c1a4d3e" }'
```

Котировка действует 60 секунд. Повтор без подтверждения вернёт новый `402` с новой ценой. Если к
моменту списания доплата подорожала, придёт `409` `quote_mismatch` со свежими `quote_token` и
`expires_at`: повторите запрос с ними. Вне этого режима `confirm_payg_topup` и `quote_token`
игнорируются.

### 402 · `payg_topup_required` — payg_topup_required — нужно подтвердить доплату

| Что произошло | Что делать |
| --- | --- |
| Заказ не создан, деньги не списаны. Вместо этого сервер прислал цену доплаты. Тело: `reason: "payg_topup_required"`, `shortfall_tokens`, `shortfall_lmc`, `shortfall_lmc_minor`, `quote_token`, `expires_at`. Этот ответ приходит только в режиме явного подтверждения доплаты. По умолчанию доплата сверх квоты списывается автоматически. | Покажите пользователю `shortfall_lmc` и получите явное согласие. Автоматический повтор здесь означает списание денег без ведома пользователя. Котировка действует недолго, по умолчанию 60 секунд (`expires_at`). Если она истекла, запрос без подтверждения вернёт новый 402 с новым `quote_token`. |

`Retry-After`: нет. Разбор: https://lumean.app/developers/docs/errors/payg-topup-required

### 409 · `quote_mismatch` — quote_mismatch — цена доплаты изменилась

| Что произошло | Что делать |
| --- | --- |
| Подтверждённая доплата не прошла: заказ не создан, ничего не списано. Тело: `reason: "quote_mismatch"`, `actual_lmc_minor` (цена сейчас), `quoted_lmc_minor` (цена в котировке), а также свежие `quote_token` и `expires_at`. Код приходит только в режиме явного подтверждения доплаты. | Покажите пользователю новую цену и снова получите согласие. Новая цена — `actual_lmc_minor`, в минорных единицах LMC. Свежий `quote_token` в этом ответе выдан уже на новую сумму. Прежний токен не подойдёт: пока цена выше котировки, запрос с ним снова вернёт 409. |

`Retry-After`: нет. Разбор: https://lumean.app/developers/docs/errors/quote-mismatch

**Правильно**

Показать пользователю `shortfall_lmc`, дождаться согласия и повторить запрос с `quote_token` из того
же ответа.

**Неправильно**

Повторять `402` с `confirm_payg_topup: true` автоматически: это списание денег без ведома
пользователя.

## Минимальные единицы

Денежные поля с суффиксом `_minor`, а также `price_units`, приходят целыми числами в минимальных
единицах. Реальное значение — `minor / 10^precision`. `precision` берите из данных: у заказа —
`currency_asset.precision`, у сервиса — `lumc_precision`. Например, `shortfall_lmc_minor: 360000000`
при `precision: 8` — это 3,6 LMC.

Для показа пользователю берите готовые `shortfall_lmc` и `price_formatted`.

## Оплата в заказе

| Поле | Что значит |
| --- | --- |
| `total_tokens` | полная стоимость в токенах, включая повторы и перегенерации |
| `tokens_from_quota` | сколько покрыла квота подписки |
| `tokens_from_payg` | сколько оплачено с баланса |
| `tokens_spent` | сумма двух предыдущих полей |
| `price_units` | сумма, заблокированная под заказ, в минимальных единицах LMC |
| `price_formatted` | та же сумма, готовая к показу |

Нулевая доля приходит как `null`, а не `0`. У заказа, целиком покрытого квотой, `tokens_from_payg`
равен `null`.

Пополнить баланс и купить тариф по API-ключу нельзя. Это делается в кабинете:
[кошелёк](/wallet), [тарифы](/shop), [лимиты аккаунта](/limits).

---

- Эта же страница в браузере: https://lumean.app/developers/docs/guide/billing
- Машинный справочник целиком: https://api.lumean.app/docs/llm.md