Rate limits
Fotovid's three-tier limiting — request rate, generation rate, and concurrency — and how to read the headers and back off.
Fotovid applies limits at three tiers. The first two are rate limits
(requests per minute); the third is a concurrency limit (how many tasks run
at once). All three return 429 when tripped, each with its own error
code.
| Tier | Limits | 429 code |
|---|---|---|
| L1 | API requests per minute, per key | RATE_LIMIT_EXCEEDED |
| L2 | Generation rate per minute, by media type (image / video / audio, each its own bucket) | RESOURCE_LIMIT_EXCEEDED |
| L3 | Concurrent tasks in flight, per account | CONCURRENT_LIMIT_EXCEEDED |
Reading the headers
L1 sets these on every response so you can pace yourself before hitting a limit:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Your quota. |
X-RateLimit-Remaining | Requests left in the current window. |
X-RateLimit-Reset | When the window resets (Unix seconds). |
Retry-After | On a 429, seconds to wait before retrying. |
L2 reports the same information under X-RateLimit-Resource-Limit,
-Resource-Remaining, and -Resource-Reset, plus Retry-After on a 429. L3
(concurrency) returns 429 CONCURRENT_LIMIT_EXCEEDED without rate headers —
retry once a task finishes.
A 429 response
{
"type": "https://api.fotovid.co/errors/rate-limit",
"title": "Rate Limit Exceeded",
"status": 429,
"code": "RATE_LIMIT_EXCEEDED",
"detail": "You have exceeded the rate limit. Please retry after 60 seconds."
}Handling limits
On a 429, honor Retry-After (fall back to exponential backoff if it's
absent), and branch on the error code to tell the tiers apart:
RATE_LIMIT_EXCEEDED and RESOURCE_LIMIT_EXCEEDED clear on a timer, whereas
CONCURRENT_LIMIT_EXCEEDED clears as your in-flight tasks complete — so the fix
there is to slow submission, not just wait.
Your per-key request rate defaults to 60 requests/min and can be set per key — see Authentication.