Core concepts

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:

BucketRequestsLimit
WritePOST, PUT, PATCH, DELETE: everything that creates or changes something, including all job-creating endpoints60 per minute
ReadGET requests: polling jobs, listing voices, getting files300 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:

HeaderDescription
X-RateLimit-LimitThe limit of the bucket this request counted against.
X-RateLimit-RemainingRequests left in the current window.
Retry-AfterOnly 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));
  }
}
Poll less, receive more

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.