Rate limits and what each refusal means
How many requests a minute you can make, which headers tell you where you stand, and how to tell a rate limit from an out-of-credits refusal.
Updated August 28, 2026
The limit is per key, per minute
Each API key has its own allowance of requests per minute, set by the workspace's plan. Keys do not share it: one runaway script cannot starve your other keys.
| Plan | Per key | Per workspace |
|---|---|---|
| Free | 60 | 60 |
| Pro | 150 | 300 |
| Max | 300 | 600 |
| Starter (org) | 300 | 600 |
| Ultimate | 600 | 1,200 |
| Business (org) | 750 | 1,500 |
| Enterprise (org) | 1,500 | 2,000 |
Two limits, and they answer different questions. The per-key limit stops one runaway script starving your other keys. The per-workspace ceiling is what the platform can actually serve you: every call against a workspace settles through the same credit meter, so adding keys does not add throughput.
A refusal says which one you hit — error.details.scope is key or workspace, and the same value comes back in an X-RateLimit-Scope header. If you are hitting the workspace ceiling, more keys will not help; spreading work across workspaces will.
Both are a ceiling on request rate, not on spend. Credits bound the cost; these bound the pace.
Knowing where you stand
Every refusal carries the standard headers:
Retry-After: 12
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1787918337
Retry-After is in seconds and is the only one you need to act on. Waiting it out is always correct; retrying immediately is not.
Telling the refusals apart
Three different things can refuse a call, and they want different responses from you. The error.code distinguishes them — do not branch on the HTTP status alone.
| Code | Status | What it means | What to do |
|---|---|---|---|
rate_limited | 429 | Too many requests this minute | Wait Retry-After seconds |
quota_exceeded | 429 | Out of credits, or past a velocity cap | Top up, or upgrade |
payment_required | 402 | The tool is not on your plan, or the workspace is suspended | Read the message; it says which |
service_unavailable | 503 | The tool is switched off, or the meter is briefly unreachable | Honour Retry-After — it is seconds for a meter blip and an hour for a disabled tool |
Both 429s are worth handling separately. A rate limit clears on its own in under a minute; running out of credits does not clear until somebody does something about it, and retrying will not help.
Concurrency
The rate limit is per key, but throughput is ultimately bounded per workspace — every call against one workspace settles against the same credit meter. In practice a single workspace sustains tens of requests a second comfortably. If you need more than that, spread work across workspaces rather than across keys in one.
Being a good client
- Honour
Retry-After. It is the number we would pick for you. - Back off exponentially on 5xx, which are transient by definition.
- Do not retry a 402 or a
quota_exceeded429 without changing something first. - One key per integration. Limits are per key, so separate keys keep a batch job from starving an interactive one.
Related
What a response tells you, and what it cost
Every call answers in the same envelope. This is what each field means, and how to read the cost of a call that spent from both credit balances.
Quickstart: your first task with ToolsXpo Code
Install the extension, sign in from your browser, and give the agent its first task — about five minutes end to end.
Scheduled automation
Run a tool, a model, or both on a schedule — and have the result emailed, POSTed to your server, or saved.
AI tools: what they are and how they differ
A handful of our tools call an AI model instead of running in your browser. That changes three things: where your data goes, what a call costs, and whether you need an account.