Лимиты и контроль расходов Heli API: бюджеты, алерты, политики

Heli работает по предоплате: запросы оплачиваются с рублёвого баланса, и при нехватке средств API отвечает 402, а не уводит счёт в минус. Но предоплата защищает только от долга, не от лишних трат. Ошибка в цикле, утёкший ключ или слишком дорогая модель в проде могут быстро съесть баланс. Ниже — какие инструменты контроля есть в кабинете и что стоит сделать на своём backend.

Где смотреть расход

«Баланс» — текущий остаток предоплаченного кошелька.
«Дашборд» — расход по дням, моделям, проектам, ключам и полю user. Здесь видно, какая модель или какой ключ даёт основную часть трат.
«Выгрузка» — журнал запросов в CSV или JSON за выбранные даты с фильтрами по ключу, проекту, пользователю и модели. Тексты промптов и ответов не хранятся.
До запуска оцените стоимость сценария в калькуляторе, а цены моделей сверяйте со страницами каталога.

Организация, дашборд и выгрузки

Калькулятор стоимости

Бюджеты и алерты

Во вкладке «Лимиты» задаются бюджеты в рублях на день, неделю или месяц. Бюджет можно назначить на весь аккаунт, на проект или на отдельный ключ. Ограничения разных уровней действуют одновременно.

При 50, 80, 90 и 100% расхода на почту приходит письмо. При достижении 100% есть два режима: остановить запросы (API ответит 429 с кодом budget) или переключать их на указанную резервную модель, обычно более дешёвую.

Ошибка 429: rate limit и бюджет

Политики на ключ и проект

Allowlist моделей — ключ работает только с перечисленными моделями; denylist запрещает модели и имеет приоритет. Запрещённая модель получает 400 model_denied.
Потолок max_output_tokens: запрос с большим max_tokens отклоняется с кодом max_tokens.
RPM на ключ: при превышении — 429 «Rate limit reached for this API key».
Политики можно менять и через API.

curl

curl https://getheli.ru/v1/org/policies \
  -X PUT \
  -H "Authorization: Bearer $HELI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "key",
    "scope_id": "key_…",
    "allow_models": ["openai/gpt-5.4-mini", "deepseek/deepseek-v4-flash"],
    "max_output_tokens": 2000,
    "on_limit": "degrade",
    "fallback_model": "deepseek/deepseek-v4-flash"
  }'

Что сделать на своём backend

Свой rate limit по user_id или tenant_id, чтобы один клиент не израсходовал общий бюджет.
max_tokens в каждом запросе.
Отдельный ключ на каждое приложение или окружение: так расход и бюджеты разделены, а утёкший ключ можно отозвать, не останавливая остальное.
Кэширование повторяющихся промптов и ответов.
Обработка 402 и 429 code budget как отдельных ситуаций: повторные запросы их не исправят.

Безопасность ключа

Ошибка 402 insufficient balance