Rate limits
Request limits per API key, the headers that report them, and how to back off.
Limits are counted per API key over a one-minute window, in two separate buckets:
| Bucket | Requests | Limit |
|---|---|---|
| Write | POST, PUT, PATCH, DELETE: everything that creates or changes something, including all job-creating endpoints | 60 per minute |
| Read | GET requests: polling jobs, listing voices, getting files | 300 per minute |
The same limits apply to v1 and v2. Need more? Contact us through the studio.
Headers
Every authenticated response tells you where you stand:
| Header | Description |
|---|---|
X-RateLimit-Limit | The limit of the bucket this request counted against. |
X-RateLimit-Remaining | Requests left in the current window. |
Retry-After | Only on 429: seconds to wait before retrying. |
When you hit the limit
The API answers 429 Too Many Requests with the code quota_rate_limited and a Retry-After header:
HTTP/1.1 429 Too Many Requests
Retry-After: 18
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Content-Type: application/json
{
"error": {
"code": "quota_rate_limited",
"message": "Too many requests",
"details": { "limit": 60, "window_sec": 60, "retry_after_sec": 18 },
"request_id": "c1f2e3d4-5b6a-4789-9abc-def012345678"
}
}Wait at least Retry-After seconds, then retry. For 5xx errors, back off exponentially with jitter.
async function withRetry(doRequest, attempts = 5) {
for (let i = 0; ; i++) {
const res = await doRequest();
if (res.status !== 429 && res.status < 500) return res;
if (i === attempts - 1) return res;
const retryAfter = Number(res.headers.get("retry-after"));
const backoff = retryAfter > 0 ? retryAfter * 1000 : Math.min(30_000, 500 * 2 ** i) * (0.5 + Math.random());
await new Promise((r) => setTimeout(r, backoff));
}
}import random
import time
def with_retry(do_request, attempts=5):
for i in range(attempts):
res = do_request()
if res.status_code != 429 and res.status_code < 500:
return res
if i == attempts - 1:
return res
retry_after = int(res.headers.get("Retry-After", "0") or 0)
backoff = retry_after if retry_after > 0 else min(30, 0.5 * 2**i) * (0.5 + random.random())
time.sleep(backoff)Polling jobs is the most common reason to hit the read limit. Pass webhook_url when you create a job and Voiser will call you when it finishes. See Webhooks.
Concurrent jobs
Separately from request limits, an account can only run a certain number of jobs at the same time. Extra jobs fail fast with 429 and job_concurrency_limit; retry once some of your running jobs have finished.