> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tronrental.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Расходы и ошибки

> max_price_trx, ключи идемпотентности, суточный лимит расходов и коды ошибок, которые встречает подключённое приложение

## Сначала цена, потом покупка с `max_price_trx`

Подключённое приложение обязано передавать `max_price_trx` в `buy_energy` и `buy_bandwidth`. Без него вызов завершается ошибкой `MAX_PRICE_REQUIRED` — суточному лимиту нужно знать, сколько вызов может стоить максимум.

1. Вызовите `quote_energy` (или `quote_bandwidth`) с объёмом и длительностью.
2. Покажите пользователю `total_trx` из котировки.
3. Вызовите `buy_energy` с теми же объёмом и длительностью и `max_price_trx` = `total_trx` из котировки.

Если цена поднимется выше `max_price_trx`, покупка отклоняется с `PRICE_CHANGED` и ничего не списывается. Запросите цену снова и спросите пользователя.

Для API-ключа `max_price_trx` необязателен, но мы рекомендуем его по той же причине.

## Ключи идемпотентности

Инструменты, которые что-то создают, принимают `idempotency_key` — заголовок [`Idempotency-Key`](https://docs.tronrental.com/ru/api-reference/energy/buy-energy) своего маршрута. Генерируйте новый UUID для каждого нового действия и **используйте его повторно, когда повторяете то же действие** после таймаута или потерянного ответа: сервер вернёт первый результат, а не спишет снова. Ключ живёт 24 часа, его длина — не больше 64 символов.

| Инструмент | Маршрут |
| - | - |
| `buy_energy` | `POST /energy/buy` |
| `buy_bandwidth` | `POST /bandwidth/buy` |
| `buy_package` | `POST /transfer-packages/buy` |
| `activate_smart_mode` | `POST /smart-mode/activate` |
| `create_auto_bw` | `POST /bandwidth/auto` |
| `create_energy_autorefill` | `POST /energy/auto-refill` |
| `create_bandwidth_autorefill` | `POST /bandwidth/auto-refill` |
| `activate_resale` | `POST /sublease/activate` |
| `generate_resale_address` | `POST /sublease/generate` |
| `create_broadcast_slug` | `POST /broadcast/slugs` |
| `stake` | `POST /account/stake` |
| `withdraw` (только API-ключ) | `POST /account/withdrawal` |

Тот же ключ с другим запросом отклоняется с `IDEMPOTENCY_KEY_REUSED`; ключ, чей первый запрос ещё выполняется, отвечает `IDEMPOTENT_REQUEST_IN_PROGRESS` — подождите и повторите с тем же ключом.

## Суточный лимит расходов

Каждое подключение может потратить заданную сумму за любые 24 часа — **100 TRX**, если пользователь не выбрал другую сумму на экране согласия или в разделе **Подключённые приложения**. Снять лимит может только владелец аккаунта.

* Перед вызовом, который тратит деньги, сервер резервирует максимум, который он может стоить: `max_price_trx` плюс активация нового адреса для покупок, цена для Smart Mode, пакетов, активаций и тарифов Node API, сумма для стейка.
* После вызова резерв превращается в реальную сумму или снимается, если ничего не списано. Если исход неизвестен (таймаут), резерв остаётся на 24 часа — при сомнении лимит выбирает отказ.
* Списания, которые идут сами (`recurring`), в лимит не входят.
* Раздел **Подключённые приложения** в личном кабинете показывает, сколько каждое приложение потратило за последние 24 часа.

Вызов, который не помещается в лимит, завершается ошибкой `AGENT_SPEND_CAP`:

```json theme={null}
{
  "error": {
    "code": "AGENT_SPEND_CAP",
    "message": "This app may spend 5 TRX a day; 2.90065 TRX is left and this call may cost up to 3.3 TRX. A call whose answer was lost may have gone through: check the orders before retrying",
    "status": 409,
    "cap_trx": "5",
    "remaining_trx": "2.90065",
    "required_trx": "3.3"
  }
}
```

> [!NOTE]
>
> Повтор покупки с потерянным ответом снова резервирует её сумму. Рядом с лимитом проверьте `list_orders` перед повтором: первый вызов мог пройти.

## Источник заказа

Заказы, созданные подключённым приложением, содержат `"source": "agent"` — в `get_order`, `list_orders` и в [вебхуке `order.updated`](https://docs.tronrental.com/ru/api-reference/webhooks/overview). Заказы, созданные с API-ключом, содержат `"source": "api"`.

## Коды ошибок

По MCP ошибка приходит как результат инструмента с `isError: true`:

```json theme={null}
{"error": {"code": "MAX_PRICE_REQUIRED", "message": "Pass max_price_trx: the quote's total_trx", "status": 422}}
```

По REST тот же код приходит в [стандартном формате ошибок](https://docs.tronrental.com/ru/errors.md).

| Код | HTTP | Значение и что делать |
| - | - | - |
| `AGENT_SPEND_CAP` | `409` | Вызов не помещается в суточный лимит подключения. `cap_trx`, `remaining_trx` и `required_trx` показывают, на сколько. Попросите пользователя поднять лимит в разделе «Подключённые приложения» или подождите |
| `MAX_PRICE_REQUIRED` | `422` | Покупка подключённым приложением без `max_price_trx`. Сначала запросите цену и передайте `total_trx` из котировки |
| `AGENT_SPEND_UNBOUNDED` | `403` | Это действие пока недоступно подключённым приложениям. Используйте личный кабинет или API-ключ |
| `AGENT_ROUTE_CLOSED` | `403` | Маршрута нет в [каталоге инструментов](https://docs.tronrental.com/ru/agents/reference/tools.md), поэтому подключённое приложение не может вызвать его по REST |
| `API_KEY_DEPOSIT_REQUIRED` | `403` | Для покупок нужны пополнения на 100 TRX в сумме. `required_trx` и `missing_trx` показывают, сколько осталось. Покажите адрес для депозита, затем подключитесь заново |
| `OAUTH_UNCAPPED_OWNER_ONLY` | `403` | Участник команды попытался снять суточный лимит. Это может только владелец аккаунта |
| `OAUTH_GRANT_LIMIT_REACHED` | `409` | У аккаунта уже максимальное число подключённых приложений (`limit`). Сначала отключите одно |
| `PRICE_CHANGED` | `409` | Цена выше `max_price_trx`. Ничего не списано; запросите цену снова |
| `VALIDATION_ERROR` | `422` | У аргумента неверный тип или он отсутствует. Проверьте `inputSchema` инструмента |
| `INTERNAL_ERROR` | `5xx` | Ошибка сервера без кода. Для покупок проверьте `list_orders`, прежде чем повторять с тем же `idempotency_key` |

Все остальные коды — коды REST API, см. [Ошибки](https://docs.tronrental.com/ru/errors.md).

Истёкший или отозванный токен получает HTTP `401` с `WWW-Authenticate: Bearer ... error="invalid_token"` на сам запрос `/mcp`; MCP-клиенты тогда обновляют токен или просят пользователя войти снова.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.