MCP rate limits and error codes
Keyless limits of 10 requests a minute and 200 a day per IP, 60 a minute with a free key, and the 401, 403, 429 and 503 errors you can get.
On this page
Rate limits
Two tiers. No account or key is needed: without a key you are on the keyless tier; a free key (Getting started) moves you to the keyed one.
| Keyless | With a free key | |
|---|---|---|
| Tool calls | 10 a minute and 200 a day, per IP address | 60 requests a minute, per key |
| Connecting and listing tools | Free; a flood ceiling of 60 a minute per IP | Counted in the 60 |
shamela_read (unit: 'range') | Up to 5 pages per call | Up to 20 |
shamela_read (unit: 'section') | Up to 10 pages per call | Up to 100 |
All windows are sliding. A refused call spends nothing — hitting the per-minute limit does not eat into the daily one.
Keyless limits are counted per IP address, because there is nothing else to count on. All keyless callers also share one pool of capacity, so at a busy moment a keyless call can be refused before you reach your own limit; the error says so. A shorter page range is not a lost page: the response says where to continue.
Keyed limits are counted against the key, not your IP address. MCP clients often sit behind shared networks, and every search runs against a shared library service, so the cost is real regardless of where the request came from.
Every response carries the current state:
| Header | Meaning |
|---|---|
ratelimit-limit | The ceiling that is closest to being reached. |
ratelimit-remaining | Requests left under that ceiling. |
ratelimit-reset | Seconds until its window resets. |
Exceed a limit and you get 429 with a retry-after header and a message naming which limit you hit. Wait that long and resume — or, if the message is about the keyless tier, add a key.
One
shamela_search_librarycall is one request against your limit, even though it may run two passes internally.
The four errors to handle
A request with no key is never refused for lacking one. A key that is sent is checked, and a bad one is refused rather than quietly treated as keyless — otherwise you would never learn it had stopped working.
Every error body is a JSON-RPC error with id: null, so the code tells you which case you hit even when the status is hidden.
| Status | JSON-RPC code | Meaning | What to do |
|---|---|---|---|
| 401 | -32001 | A key was sent and is not valid. | Check the Authorization: Bearer … header. If the key was deleted, create a new one — or remove the header to continue on the keyless tier. |
| 403 | -32003 | The key is valid but may not use the server: its account is suspended. | See Banned accounts. |
| 429 | -32004 | A rate limit was reached; the message says which. The Retry-After header says how many seconds to wait. | Wait, then retry. Keyless callers can also add a free key. |
| 503 | -32002 | Your key could not be verified right now, so the request was refused rather than waved through. | Transient. Retry after the Retry-After header (30 seconds). |
A 503 means the server could not confirm your key was valid, so it refused the request rather than guessing. It never admits an unverifiable key — a request that cannot be authenticated is rejected, not waved through. A key that was verified in the last ten minutes is still accepted while the accounts service is briefly failing, so a transient outage does not lock out a working key. A key that is genuinely invalid is always a 401, never a 503: if you keep getting 401, retrying will not help.
Malformed requests and server faults
Besides those four, the server sends only these, which a normal MCP client never triggers:
| Status | JSON-RPC code | Meaning | What to do |
|---|---|---|---|
| 400 | -32700 | The body is not valid JSON. | Fix the request; retrying it unchanged fails the same way. |
| 400 | -32600 | The body is JSON but not a JSON-RPC 2.0 request (missing jsonrpc: "2.0" or method, or a batch). | Send one request per POST — MCP 2025-06-18 has no batching. |
| 500 | -32603 | An unexpected fault on the server. | Retry once after a few seconds; if it persists, the fault is ours. |
A 502 or 504 does not come from the MCP server — it comes from the proxy in front of it while the server is restarting or unreachable. Treat it like a 500 and retry shortly.
Two kinds of failure
Once you are authenticated, failures arrive in one of two shapes, and the difference is deliberate.
A tool error comes back as a normal result marked isError, with a message your assistant can read and act on. Send an invalid scope — to shamela_search_library or to any shamela_* search that takes one — and you get the list of valid ones back, so the model can simply retry with a real scope. A query with no Arabic words gets a message to translate it and call again:
scope is required and must be one of: hadith-primary, tafsir-canonical, fiqh-hanafi, …
A protocol error comes back as a JSON-RPC error, for problems your assistant cannot fix by trying again — asking for a tool that does not exist, or sending a malformed request.
| Situation | Shape |
|---|---|
Missing or invalid scope | Tool error (isError) |
Empty query | Tool error (isError) |
| Library drops out during a call | Tool error (isError) |
| Library already unreachable when you call | Protocol error -32601 (see below) |
| Unknown tool name | Protocol error -32601 |
| Malformed JSON-RPC request | Protocol error -32600 |
The split matters because many clients never show a protocol error to the model — it just sees the call fail. Putting recoverable mistakes in the result is what lets an assistant correct itself instead of giving up.
When the library is unavailable
If the library service cannot be reached, tools/list returns no tools rather than advertising one that would fail mid-call, and any attempted call returns protocol error -32601 with a message saying the library is temporarily unreachable. This is HTTP 200, not a 503.
This is why a client that suddenly lists zero tools is showing you a real signal, not a configuration problem. Give it a minute and reconnect.
Losing a key
Keys cannot be recovered — only a hash is stored. If you lose one or think it has leaked, delete it first, then create a replacement. Deleting first closes the window in which someone else holds a working key.
Revocation takes up to 60 seconds to reach this endpoint. Verified keys are cached for a minute so that every tool call does not require a round trip to the accounts service. A key you just deleted may keep working until that minute is up — measured at ~6 seconds in practice, but plan for 60.
That window matters when you are revoking a leaked key rather than tidying up. Delete it immediately anyway; then treat the next minute as still-exposed rather than assuming the door shut the moment you clicked.
Full key management is covered in API keys.