Limits and errors
Rate limits, every error you can get back, and which ones are worth retrying.
On this page
Rate limit
60 requests per minute per key, sliding window.
The limit is counted against the key, not your IP address. Two reasons: 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 | Your ceiling — 60. |
ratelimit-remaining | Requests left in this window. |
ratelimit-reset | Seconds until the window resets. |
Exceed it and you get 429 with a retry-after header. Wait that long and resume.
One
search_librarycall is one request against your limit, even though it may run two passes internally.
Authentication errors
| Status | Meaning | What to do |
|---|---|---|
| 401 | No key sent, or the key is not valid. | Check the Authorization: Bearer … header. If the key was deleted, create a new one. |
| 403 | The account owning the key is suspended. | See Banned accounts. |
| 429 | Rate limit exceeded. | Wait for retry-after, then retry. |
| 503 | Key verification is temporarily unavailable. | Transient. Retry after ~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.
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 and you get the list of valid ones back, so the model can simply retry with a real scope:
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 temporarily unreachable | Tool error (isError) |
| 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 an error saying the library is temporarily unreachable.
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.