Key limits, idempotency and caching
API Reference
Three things agents and pipelines need more than a discount: spend control, protection from paying twice, and free replays.
Per-key limits
Every key in the dashboard can have a daily and monthly spend cap and a list of allowed models. An experiment key — no more than $2 a day; a support-bot key — only qwen3.5-flash.
The check runs before the request reaches the model, so a rejected request costs nothing.
| Situation | Response |
|---|---|
| Model not in the key's list | 403, code model_not_allowed_for_key |
| Daily cap reached | 429, code key_daily_limit_reached — resets at 00:00 UTC |
| Monthly cap reached | 429, code key_monthly_limit_reached |
Other keys on the account keep working: the limit is per key, not per balance.
Idempotency-Key
A pipeline with retries can send the same request twice — and pay twice. Send an Idempotency-Key header with any unique value: a repeat with the same key returns the stored response and is not charged again.
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":"Classify: ..."}]}'The same key with a different body — 422, code idempotency_conflict: one key, one request. Stored responses live for 24 hours.
Content cache
An identical request — same model, same body, temperature: 0 — is served from cache for free the second time. A pipeline restarted halfway does not pay for work already done.
- With
temperature: 0the cache is on by default. - With any other temperature, opt in:
X-Zukko-Cache: true. - Turn it off regardless:
X-Zukko-Cache: false.
A hit is visible in the response header X-Zukko-Cache: hit (or idempotent-replay for a key-based replay). The cache is per account, errors are never cached, streaming and non-streaming responses are stored separately. Retention — 7 days.
Cost in the response
Every successful response carries X-Zukko-Cost-Micros — the cost of this request in microdollars (1,000,000 = $1) — and X-Fetch-Balance-Cents — the balance after the charge. An agent can watch its own spend and stop before zero rather than after.