Skip to content

Rate Limits

The API allows a fixed number of requests per 10-minute window, per API key. The window slides continuously; it doesn’t reset on a fixed clock interval.

In practice: if you make 250 requests in the first minute on the Free plan, you must wait ~9 minutes before your first request exits the window and you can send another.

Request bodies are limited to 1 MiB (1,048,576 bytes), with a 10 MiB limit on /leads/batch. Larger requests return 413 Payload Too Large. The limits also cover chunked bodies and trailing data after JSON.

Plan Requests Window
Free 250 10 minutes
Pro 2,500 10 minutes
Scale 5,000 10 minutes

All API keys, assistant connections and dashboard sessions of one account also share an account budget, counted in the same 10-minute window. The budget is the per-key limit times the plan’s API key limit, or times the number of active keys and assistant connections when the account has more (for example after a downgrade).

Plan Requests per account Window
Free 2,500 10 minutes
Pro 62,500 10 minutes
Scale 250,000 10 minutes

A request is counted only when both its key’s limit and its account’s limit allow it. A refused request uses neither budget. A replay counts as a request.

Authenticated API responses include rate limit headers:

Header Description
X-RateLimit-Limit Max requests allowed in the window
X-RateLimit-Remaining Requests remaining in the current window
X-RateLimit-Reset Unix timestamp when the next slot frees in the sliding window
X-RateLimit-Scope Which limit the other headers describe: credential (the API key, assistant connection or dashboard session) or account
Retry-After Seconds to wait before retrying (only present on 429 responses)

The headers describe whichever of the two limits has less room left, as named by X-RateLimit-Scope. It is usually the key’s own limit.

These headers (including X-RateLimit-Reset, X-RateLimit-Scope and Retry-After) are exposed to browsers via CORS.

When the limit is exceeded, the API returns 429 Too Many Requests:

{
"error": "rate_limit_exceeded",
"message": "Rate limit exceeded",
"code": "rate_limit_exceeded"
}

Unauthenticated requests (missing X-API-Key) are not counted; they return 401 directly.

A 429 can also come from our network edge, before it reaches the API, and its body may not be JSON. If a 429 has no Retry-After header, wait at least 10 seconds before retrying.

Read the Retry-After header and pause before retrying. Use exponential backoff for repeated 429s:

import time, requests
def api_call_with_retry(url, headers, max_retries=3):
for attempt in range(max_retries):
resp = requests.get(url, headers=headers)
if resp.status_code == 429:
retry_after = int(resp.headers.get("Retry-After", 60))
time.sleep(retry_after * (2 ** attempt)) # exponential backoff
continue
return resp
raise Exception("Rate limit retries exhausted")

Upgrade to Pro from your dashboard to get 10× the rate limit.

Limits are shared across instances and MCP tool calls and persist across server restarts. They are counted by API key ID after authentication. Large limits use an interpolated estimate from the current and previous windows; timing around a window boundary can differ from an exact request log. New keys are published through database notifications, without waiting for a periodic admission-index refresh. If a creation notification is lost, an index miss can recover the key through a live lookup, globally limited to one lookup per service instance every two seconds after the previous lookup finishes. A new key may receive 401 while this budget is occupied; an independent refresh runs every 60 seconds as fallback. Unknown and revoked keys, exhausted lookup budgets and lookup failures all return the same 401 on an index miss. Login, signup, password reset, OAuth and public forms also have separate network abuse limits. A refusal returns HTTP 429 with Retry-After.

X-RateLimit-Reset reports the next window boundary while capacity remains, or the next estimated admission when exhausted. It is separate from the internal two-window storage expiry; a 429 includes Retry-After.

OAuth authorization and token exchange (including refresh) have separate network quotas. On token exchange and refresh, verified requests from Anthropic’s published outbound network have capacity of 6,000 requests per minute per address and client/address pair, to support shared Claude server traffic. Authorization keeps its normal network quotas. Client and refresh-family quotas still apply. This capacity does not grant access or change API quotas. Discovery and browser consent have no separate network quota. Dynamic registration retains its existing limits.

Free accounts can have 10 active API keys, Pro 25 and Scale 50. Creating another key at the limit returns an explicit error; revoke or delete a key first. Disabled and expired keys do not count. A downgrade keeps existing keys but blocks new keys until the account is below its new limit. These limits also apply to legacy MCP OAuth key issuance. Banned accounts cannot use API keys on REST or MCP; an expired temporary ban no longer blocks access.