Rate limits
Limits protect you from runaway scripts and keep the service fair. They are per key, and generous for normal use.
Limits
| Bucket | Limit | Applies to |
|---|---|---|
| Creates | 120 per minute per key | POST /v1/files, /complete, DELETE /v1/files/{id}, POST /v1/audio/denoise, /cancel |
| Reads | 1,200 per minute per key | GET on files, jobs, outputs, credits and /v1/me |
| Public | 120 per minute per IP address | GET /v1/models, GET /v1/status |
Limits are token buckets: unused capacity refills continuously, so short bursts are fine. Live and test keys are counted separately. Need more? Email support@zilapi.com.
Headers
| Header | Meaning |
|---|---|
| RateLimit-Limit | The bucket's size, for example 1200. |
| RateLimit-Remaining | Requests left right now. |
| RateLimit-Reset | Seconds until the bucket is full again. |
| Retry-After | On 429 (and 503): seconds to wait before retrying. |
Handling 429
Over a limit you get 429 rate_limited with Retry-After. Wait that long, then retry; add a little jitter when many workers share a key. Upload quotas use 429 quota_exceeded (see Files).
Retry on 429 and 503 with Retry-After
# --retry honours Retry-After on 429 and 503
curl -s --retry 5 --retry-max-time 120 https://api.zilapi.com/v1/jobs/$JOB_ID -H "Authorization: Bearer $ZILAPI_KEY" -D headers.txt
grep -i '^ratelimit-' headers.txt # RateLimit-Limit: 1200, RateLimit-Remaining: 1199, RateLimit-Reset: 1