Rate Limits
Request quotas, 429 responses, and how to back off correctly
Rate Limits
Every /api/v1/* request counts against one budget per account:
| Scope | Limit |
|---|---|
All /api/v1/* endpoints | 60 requests per minute |
The window is a fixed 60-second bucket keyed by your account — not per endpoint and not per API key. Two keys on the same account share the budget, and polling a task costs exactly as much as creating one.
This number is small on purpose: a 2-second poll loop uses 30 of your 60 requests. If you run several tasks at once, poll less often or batch your reads — see Tasks & Polling.
When you exceed it
HTTP/2 429
retry-after: 12
x-ratelimit-remaining: 0
x-ratelimit-reset: 1723000060{
"error": {
"message": "Rate limit exceeded",
"type": "rate_limit_error",
"code": null,
"param": null
}
}| Header | Meaning |
|---|---|
Retry-After | Seconds to wait before your next request will be accepted |
X-RateLimit-Remaining | Always 0 on a 429 |
X-RateLimit-Reset | Unix timestamp (seconds) when the window resets |
Honour Retry-After rather than guessing. Requests rejected with 429 are not
charged credits and did not create a task.
Backing off
async function requestWithRetry(url: string, init: RequestInit) {
for (let attempt = 0; attempt < 4; attempt++) {
const res = await fetch(url, init);
if (res.status !== 429) return res;
const retryAfter = Number(res.headers.get('retry-after') ?? '5');
// jitter, so parallel workers don't all wake at the same instant
const wait = retryAfter * 1000 + Math.random() * 500;
await new Promise((r) => setTimeout(r, wait));
}
throw new Error('Still rate limited after 4 attempts');
}Two rules that matter more than the retry count:
- Never retry a
POST /3d/generationsblindly. A 429 means the request was rejected before any task existed, so retrying is safe. But a 5xx is not the same thing — see Error Handling. - Back off, don't tighten the loop. Doubling the interval is usually enough; shortening it after a 429 guarantees you stay throttled.
Practical budget planning
| Workload | Requests per task | Tasks/minute at 60 rpm |
|---|---|---|
| Async + 5s polling, ~60s generation | ~13 | ~4 |
| Async + 10s polling, ~60s generation | ~7 | ~8 |
| Sync mode (single request) | 1 | ~60 |
For batch jobs, prefer mode: "sync" where the generation reliably finishes
under 55 seconds, or drive async tasks from a queue with a small number of
workers rather than polling everything in parallel.