# MCP for developers: MCP rate limits and error codes

Source: https://qurangallery.com/docs/mcp/limits-and-errors

> 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.

## Rate limits

Two tiers. No account or key is needed: without a key you are on the keyless tier; a free key ([Getting started](https://qurangallery.com/docs/mcp/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_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.

| 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](https://qurangallery.com/docs/accounts/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](https://qurangallery.com/docs/accounts/api-keys).

## Next steps

- [Open Quran Gallery MCP](https://qurangallery.com/mcp)
- [MCP prompts and custom instructions for cited answers](https://qurangallery.com/docs/mcp/custom-instructions)
- [Quran Gallery Shamela MCP: frequently asked questions](https://qurangallery.com/docs/mcp/faq)
- [MCP server for Islamic texts: what it does](https://qurangallery.com/docs/mcp/overview)
