Как ограничить расход API-ключа, чтобы агент не ушёл в минус

Агент, который застрял в цикле или получил слишком большую задачу, может за ночь потратить весь баланс. Ограничить расход API-ключа можно в несколько слоёв: отдельный ключ на каждого агента, дневной и месячный потолок, список разрешённых моделей и код, который правильно реагирует на ошибки лимитов. Разберём каждый слой и то, где смотреть фактический расход.

Отдельный ключ на каждого агента

Лимиты в Zukko задаются на ключ, а не на аккаунт. Поэтому первый шаг — завести отдельный ключ для каждого агента или пайплайна и назвать его понятно: agent-review, nightly-labeling, support-bot.

Что это даёт:

• у каждого агента свой потолок, и упёршийся в лимит агент не останавливает остальных — другие ключи продолжают работать;
• если ключ утёк или агент ведёт себя странно, его можно отозвать, не трогая остальные интеграции;
• в настройках сразу видно, какой агент к каким моделям имеет доступ.

Полный ключ показывается один раз при создании — сохраните его в переменные окружения или секреты агента. Ключи создаются в разделе API-ключи↗.

Дневной и месячный лимит

У каждого ключа можно задать потолок расхода в долларах на день и на месяц. Как это работает, по документации о лимитах ключа↗:

• Проверка идёт до обращения к модели, поэтому за отклонённый запрос ничего не списывается.
• Дневной расход обнуляется в 00:00 UTC (03:00 по Москве), месячный — в начале месяца по UTC.
• Пустой лимит или 0 — ограничения нет.
• В лимиты входят и запросы к веб-поиску.

Лимиты мягкие

Это важная деталь. Перед запросом шлюз сравнивает уже списанную сумму с потолком, а стоимость самого запроса заранее неизвестна. Поэтому последний пропущенный запрос может превысить потолок, а несколько параллельных запросов, начатых до достижения лимита, пройдут все. Если у вас пять параллельных агентов на одном ключе, перерасход может быть заметным — оставляйте запас или разводите их по разным ключам.

Как выбрать число

Оцените стоимость одного прогона агента и умножьте на число прогонов в день. Пример: агент на claude-sonnet-5 за прогон тратит 3M входных токенов (2.7M — чтение кэша, 0.15M — запись в кэш, 0.15M — свежий вход) и 0.1M выходных. По ценам за 1M токенов (вход 0.2, выход 1.013, чтение кэша 0.025, запись 0.25):

0.15 × 0.2 + 2.7 × 0.025 + 0.15 × 0.25 + 0.1 × 1.013 = 0.03 + 0.0675 + 0.0375 + 0.1013 ≈ $0.24 за прогон.

Пять прогонов в день — 5 × 0.2363 ≈ $1.18. Разумный дневной лимит — $2: обычный день помещается, а зациклившийся агент остановится примерно после восьми прогонов (2 / 0.2363 ≈ 8.5). Месячный лимит ставьте ниже, чем дневной × 30, — он ловит медленный рост расхода, который дневной не замечает.

Кэш в этом расчёте важен: у Claude скидку за кэш даёт Anthropic-формат (/v1/messages), в OpenAI-формате весь вход Claude идёт по цене входа, и тот же прогон стоил бы 3 × 0.2 + 0.1 × 1.013 ≈ $0.70. Свои реальные цифры возьмите из истории расходов после первого дня. Цены в расчёте — на 6 октября 2026 года; актуальный список и цены — GET https://api.zukko.pro/v1/models или страница «Модели» в кабинете.

allowed_models: только нужные модели

Второй потолок — список моделей, которые разрешены ключу (allowed_models). Если агенту для классификации нужны только deepseek-v4.1-flash и glm-5.3-flash, разрешите только их. Тогда ошибка в конфиге, из-за которой агент обратится к claude-fable-5-1 (3.48 / 17.4 $ за 1M против 0.013 / 0.038 у DeepSeek V4.1 Flash), закончится ошибкой 403, а не счётом.

Для агента-программиста список может быть таким: claude-sonnet-5 и claude-opus-5-5. Подробнее о настройке — в статье про allowed_models↗.

Какие ошибки получит агент и что с ними делать

Собственного ограничения частоты запросов у Zukko нет: 429 от шлюза — это только лимиты ключа, которые вы задали сами. Любой другой 429 пришёл от провайдера модели. Поэтому разбирать ошибку нужно по полю error.code, а не только по статусу.

Это особенно важно для агентов: многие клиенты по умолчанию повторяют любой 429. Официальный Python SDK OpenAI, например, повторяет 429 и ошибки 5xx автоматически. Повторы при исчерпанном лимите бесплатны, но бесполезны: агент будет крутиться до полуночи по UTC, вместо того чтобы остановиться и сообщить о проблеме.

Обработка в коде

Пример на Python: автоматические повторы SDK выключены, решение принимается по коду ошибки, а стоимость каждого запроса берётся из заголовка X-Zukko-Cost-Micros (в микродолларах, есть у обычных, не потоковых ответов).

import os
import time

import openai
from openai import OpenAI

client = OpenAI(
    base_url="https://api.zukko.pro/v1",
    api_key=os.environ["ZUKKO_AGENT_KEY"],
    max_retries=0,
)

STOP_CODES = {
    "insufficient_balance",

Функции agent_is_done и next_messages — логика вашего агента: проверка, закончена ли задача, и следующие сообщения (ответ модели, результаты инструментов). Бюджет задачи и MAX_STEPS — третий слой поверх лимитов ключа: они ограничивают одну задачу, а не весь день. Полный список кодов и правила повторов — в разделе ошибок документации и в статье об обработке ошибок и запасной модели↗.

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

• Кабинет, раздел «Использование». История расходов по запросам: время, модель, токены, стоимость. Это первое место, куда стоит заглянуть после первого дня работы агента.
• GET /v1/balance. Текущий баланс аккаунта в центах. Баланс общий для всех ключей. Дорогой запрос, начатый с маленьким остатком, может увести баланс в минус — тогда следующие запросы получат 402 до пополнения. Подробнее — в документации по балансу↗.
• GET /v1/usage. История списаний через API с пагинацией. Учтите: в ней все списания аккаунта, а не только этого ключа.

curl -G https://api.zukko.pro/v1/usage \
  -H "Authorization: Bearer $ZUKKO_AGENT_KEY" \
  --data-urlencode "limit=50"

Оба запроса бесплатные. Если нужен расход именно по агенту, суммируйте X-Zukko-Cost-Micros в его коде, как в примере выше.

Частые вопросы

Списываются ли деньги за запрос, отклонённый по лимиту?

Нет. Лимиты и список моделей проверяются до обращения к модели, поэтому отклонённый запрос ничего не стоит.

Почему агент потратил чуть больше лимита?

Лимиты мягкие: последний пропущенный запрос может перейти потолок, а параллельные запросы, начатые до достижения лимита, проходят все. Оставляйте запас или разносите параллельных агентов по разным ключам.

Когда сбрасывается дневной лимит?

В 00:00 UTC, это 03:00 по Москве. Месячный — в начале календарного месяца по UTC.

Что будет с другими ключами, когда один упрётся в лимит?

Они продолжат работать: лимит действует на ключ, а не на баланс. Но баланс у всех ключей общий, и если он закончится, 402 получат все.