Лимиты ключа, идемпотентность и кэш
API Примеры
Три вещи, которые нужны агентам и пайплайнам больше, чем скидка: контроль расхода, защита от двойной оплаты и бесплатные повторы.
Лимиты на ключ
У каждого ключа в кабинете можно задать потолок расхода в день и в месяц и список разрешённых моделей. Ключ для эксперимента — не больше $2 в день; ключ для бота поддержки — только qwen3.5-flash.
Проверка идёт до похода к модели, поэтому за отклонённый запрос ничего не списывается.
| Ситуация | Ответ |
|---|---|
| Модель вне списка ключа | 403, код model_not_allowed_for_key |
| Дневной потолок исчерпан | 429, код key_daily_limit_reached — сбросится в 00:00 UTC |
| Месячный потолок исчерпан | 429, код key_monthly_limit_reached |
Остальные ключи аккаунта продолжают работать: лимит — на ключ, а не на баланс.
Idempotency-Key
Пайплайн с ретраями может отправить один и тот же запрос дважды — и дважды заплатить. Передайте заголовок Idempotency-Key с любым уникальным значением: повтор с тем же ключом вернёт сохранённый ответ и не спишет второй раз.
curl https://api.zukko.pro/v1/chat/completions \
-H "Authorization: Bearer fetch_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: job-2026-09-15-row-4812" \
-d '{"model":"qwen3.5-flash","messages":[{"role":"user","content":"Классифицируй: ..."}]}'Тот же ключ с другим телом запроса — 422, код idempotency_conflict: один ключ — один запрос. Сохранённый ответ живёт 24 часа.
Кэш по содержимому
Одинаковый запрос — та же модель, то же тело, temperature: 0 — второй раз отдаётся из кэша бесплатно. Пайплайн, перезапущенный на половине, не платит за уже сделанное.
- При
temperature: 0кэш включён сам. - При другой temperature включите явно:
X-Zukko-Cache: true. - Выключить в любом случае:
X-Zukko-Cache: false.
Попадание видно по заголовку ответа X-Zukko-Cache: hit (или idempotent-replay для повтора по ключу). Кэш отдельный у каждого аккаунта, ошибки не кэшируются, потоковый и обычный ответы хранятся раздельно. Срок — 7 дней.
Стоимость в ответе
Каждый успешный ответ несёт X-Zukko-Cost-Micros — стоимость этого запроса в микродолларах (1 000 000 = $1) — и X-Fetch-Balance-Cents — остаток после списания. Агент может следить за расходом сам и остановиться до нуля, а не после.