Rate limits and concurrency

Two separate limits apply: how fast you can call the API, and how many generations can run at once.

Requests per minute

Each key has a sliding window of requests per minute, 60 by default. Every call counts once, reads included. Every /v1 response tells you where you stand:

RateLimit-Policy: "default";q=60;w=60
RateLimit: "default";r=57;t=31

q is the quota per window of w seconds; r is what remains and t the seconds until the window resets. These follow the IETF RateLimit header draft.

Over the limit, the API answers 429 rate_limited with a Retry-After header in seconds. Wait that long, then retry. If you need a higher limit, ask in the dashboard.

Concurrency and the queue

Your account runs up to max_concurrent generations at the same time. Creates beyond that are accepted and queued, first in, first out, up to queue_cap (50 by default). When both are full, creates answer 429 queue_full with a Retry-After between 5 and 300 seconds, estimated from how fast your queue is draining.

GET /account shows your limits and current load:

{
  "limits": { "requests_per_minute": 60, "max_concurrent": 4, "queue_cap": 50, "running": 4, "queued": 12 }
}

Staying inside the limits

• Prefer webhooks to polling. If you poll, read each generation no more than every 5 seconds.
• Cache GET /effects and GET /prices; they change at most a few times a week, and webhooks tell you when.
• Spread bursts. If your users can start many generations at once, queue them on your side and feed them in as running drops.
• Retry 429 responses only after Retry-After, with the same Idempotency-Key.