API reference
Rate limits
Rate limits are per workspace, reported on every response, and signalled with 429 plus Retry-After when exceeded.
Public API requests are rate limited per workspace, not per key. Minting more keys does not raise your ceiling, every key in a workspace draws on the same budget.
A ceiling per key
On top of the workspace limit, a key can be given its own requests per minute when it is created or edited, a lower ceiling for a key you hand to a partner or a script you do not fully trust. A key’s limit can only tighten the workspace limit, never raise it, and the headers below always describe whichever limit is closer to being hit. The console’s key list shows each key’s effective limit and the workspace ceiling.
Reading your budget
Every response, successful or not, carries three headers:
| Header | Meaning |
|---|---|
RateLimit-Limit | Requests allowed in the current window |
RateLimit-Remaining | Requests left in this window |
RateLimit-Reset | Seconds until the window resets |
Read RateLimit-Remaining as you go rather than waiting to be refused, it lets
you slow down before you hit the wall.
When you exceed it
You get 429 with the standard envelope and code: "rate_limited", plus a
Retry-After header in seconds.
HTTP/1.1 429 Too Many Requests
Retry-After: 34
RateLimit-Reset: 34{
"error": {
"code": "rate_limited",
"message": "Too many requests. Please try again later."
}
}Backing off well
Wait for Retry-After before retrying, retrying sooner just consumes the next
window. For batch work, spread requests out rather than firing them in parallel
and absorbing the 429s.
Rate limiting is separate from credits. A 429 means “too fast”; a 402
(insufficient_credits) means “out of balance”. Slowing down fixes the first and
does nothing for the second.