Rate limits & quotas
Per-minute and per-day limits by plan, the headers that report them, and how to back off.
Limits are enforced per ACCOUNT, not per key — minting more keys does not buy more throughput, and one noisy key will rate-limit the others. Every response carries the current state, so a well-behaved client never has to guess.
Authentication
Limits come from the plan of the account that owns the key. Read your own with GET /api/v1/account/api-limits; an admin can raise them per-account without changing your plan.
Create a key in Settings → API Keys. It is shown once, so copy it then. Every example below reads it from $SONICVOX_API_KEY.
Endpoints
Your quotas and recent consumption. Every response from every endpoint also carries the live headers below, so you rarely need to poll this.
- Scope
- analytics:read
- Credits
- 0
curl https://staging.sonicvox.ai/api/v1/usage \
-H "sv-api-key: $SONICVOX_API_KEY"# Headers on EVERY response
x-ratelimit-limit: 100 # requests/minute on this plan
x-ratelimit-remaining: 98 # left in the current window
x-ratelimit-reset: 1786172295 # unix seconds when it resets
x-daily-requests-limit: 10000
x-daily-requests-used: 1
x-credits-remaining: 500000
x-plan: SCALEWhen it fails
Every error carries type, code, message, request_id and a doc_url. Branch on type for retry policy.
| rate_limit_exceeded | Over the per-minute limit. Retry-After tells you how long to wait; the 60-second window starts at your first request and clears all at once, so waiting it out hands back the full allowance. |
| daily_limit_exceeded | Over the daily request allowance. It resets at 00:00 UTC — retrying sooner will not help. |
| insufficient_credits | Not a rate limit: the balance will not cover this request. Nothing was charged. |
| rate_limit | Your plan's CONCURRENT generation limit, not the per-minute one. Fewer requests in flight, not slower ones. |