Skip to content

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.

KeylessWith a free key
Tool calls10 a minute and 200 a day, per IP address60 requests a minute, per key
Connecting and listing toolsFree; a flood ceiling of 60 a minute per IPCounted in the 60
shamela_read (unit: 'range')Up to 5 pages per callUp to 20
shamela_read (unit: 'section')Up to 10 pages per callUp 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:

HeaderMeaning
ratelimit-limitThe ceiling that is closest to being reached.
ratelimit-remainingRequests left under that ceiling.
ratelimit-resetSeconds 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_library call 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.

StatusJSON-RPC codeMeaningWhat to do
401-32001A 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-32003The key is valid but may not use the server: its account is suspended.See Banned accounts.
429-32004A 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-32002Your 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:

StatusJSON-RPC codeMeaningWhat to do
400-32700The body is not valid JSON.Fix the request; retrying it unchanged fails the same way.
400-32600The 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-32603An 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.

SituationShape
Missing or invalid scopeTool error (isError)
Empty queryTool error (isError)
Library drops out during a callTool error (isError)
Library already unreachable when you callProtocol error -32601 (see below)
Unknown tool nameProtocol error -32601
Malformed JSON-RPC requestProtocol 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.

Next steps

Edit this page on GitHub