Rate limits
Every endpoint sits on one of two tiers: a read tier for listing and fetching, and a generation tier for everything that creates, changes, or reaches outward. The window counts per key and per endpoint path, not per IP address, so two of your keys never share a budget and a burst against one endpoint does not starve another.
Current ceilings, from the live feed:
Treat the ceilings as approximate and enforced best-effort. What you should build against is the refusal itself.
The 429 contract
When you exceed a window, the response is:
{
"error": "Rate limit exceeded",
"message": "Generation rate limit exceeded. Please wait before generating more content.",
"retryAfter": 24
}with these headers:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | The window’s ceiling |
X-RateLimit-Remaining | Requests left in the window, 0 on a refusal |
X-RateLimit-Reset | When the window resets, as epoch seconds |
Retry-After | Seconds to wait, the same value as retryAfter in the body |
Retry guidance: wait the full Retry-After before retrying, and back off rather than polling the moment it elapses. A rate-limited call never spends credits, so retrying is always safe on your budget.
Which tier is my endpoint on?
A few placements are deliberate rather than mechanical. Scheduling a post rides the generation tier even though it is free, because it reaches a real audience. The asset doors ride the read tier even though they write, because they are cheap and safe to call often.
Credits and the spending cap are the real budget; the rate limit is only a burst brake that keeps a runaway loop from doing damage in a single minute.