Rate limits
How many requests a key can make, what heavier calls cost and what happens when you go over.
Limits by plan
Every call spends units from two buckets: one for the key and one shared by every key in the workspace. Buckets refill continuously, so a key that waits a moment gets its allowance back.
| Plan | Per key / minute (burst) | Workspace / minute (burst) | Calls at once | API and MCP searches / billing period | Exports / day |
|---|---|---|---|---|---|
| Trial | 120 (60) | 240 (120) | 2 | 1,000 | 1 |
| Starter | 120 (60) | 240 (120) | 2 | 3,000 | 2 |
| Growth | 300 (150) | 600 (300) | 4 | 10,000 | 5 |
| Scale | 600 (300) | 1,200 (600) | 6 | 30,000 | 10 |
| Pro | 1,200 (600) | 2,400 (1,200) | 8 | 100,000 | 20 |
The search allowance counts searches through the API and MCP; searches your team runs in Hobson don't use it. The burst is how many units a full bucket holds. Trials get Trial limits whichever plan you picked. Calls at once counts calls still running across the whole workspace.
What a call costs
Reads cost 1 unit and writes cost 2. Heavier calls cost more:
| Calls | Units |
|---|---|
| Searching conversations or knowledge, Shopify order lookups, connector calls | 5 |
| Drafting a reply, translating, rule previews, exports, knowledge uploads | 20 |
| Starting an import, a draft evaluation or a full re-index | 60 |
Each action's cost is in the API reference as x-hobson-cost.
Headers
Every limited response carries the IETF rate limit headers:
RateLimit-Policy: "key";q=60;w=30, "workspace";q=120;w=30, "concurrency";q=2;qu="concurrent-requests"
RateLimit: "key";r=40;t=10, "workspace";r=100;t=5q is the burst and w the seconds a full refill takes. r is what's left now and t the seconds until the bucket is full again. Searches and exports also return Hobson-Quota-Search or Hobson-Quota-Export, for example used=1240;limit=10000;resets=2026-11-01T00:00:00Z.
When you go over
Going over returns 429 Too Many Requests with a Retry-After header and an application/problem+json body:
{
"type": "https://hobson.support/docs/rate-limits#rate-limited",
"title": "Too many requests",
"status": 429,
"code": "rate_limited",
"message": "This API key is sending requests too quickly. Try again in 10 seconds.",
"policy": "key",
"retryAfterSeconds": 10
}policy says which limit you hit: key, workspace or concurrency. A busy key is never reported as invalid, so a 401 always means the key itself is wrong.
When a search or export quota is used up you get 402 with code: "quota_exceeded" and the date it resets. Don't retry these; they won't succeed until then.
If Hobson is briefly too busy, or can't check your limits, you may get 503 with Retry-After. Retry after that many seconds.
On the MCP server, limits come back as a tool error that tells Claude how long to wait, not as an HTTP error, so the conversation carries on.
See your usage
Settings › Advanced › API keys shows each key's calls over the last 24 hours and 30 days, and how often it was rate limited in the last 7 days. Counts can lag by a minute.
Handling limits well
- Honour
Retry-After, and back off a little longer each time you're refused. - Avoid firing many calls in parallel. A few at a time is faster than a burst of refusals.
- Page through lists instead of fetching one item at a time.
- Use one key per integration so one busy script can't use up another's allowance.