MCP error shapes
The server returns standard JSON-RPC error objects, plus two MCP-specific codes: -32020 for a header that disagrees with the body or is missing, and -32022 for an unsupported protocol revision. The HTTP status carries information too: a transport problem gets a real 4xx, an unknown method is 404 for a request that declares revision 2026-07-28 and 200 for an older one, and a problem inside a valid call comes back as a result with isError: true and a code in structuredContent.error.
The codes#
| Code | HTTP | Cause | What to do |
|---|---|---|---|
-32700 | 400 | The body is not valid JSON | Fix the serialiser. Retrying sends the same broken bytes |
-32600 | 403 | A present Origin header is not recognised | Send no Origin from a non-browser client, or call from an allowed origin |
-32600 | 413 | The request body is over 256 KiB | Split the call. No documentation tool needs an argument that large |
-32600 | 400 | A JSON-RPC batch was sent | Send one message per request; batches are refused outright |
-32600 | 400 | An unsupported protocol version was asked for | Read error.data.supported and pick one of the four listed revisions |
-32020 | 400 | A header disagrees with the request body | Make the header match, or send neither |
-32600 | 400 | The message has no method and is not a response | Send a JSON-RPC request, notification or response |
-32601 | 200 | The JSON-RPC method does not exist | Check the spelling against tools/list, resources/list, prompts/list |
-32601 | 200 | The tool, resource or prompt named does not exist | List them and use a real name; the method itself was valid |
-32602 | 200 | params or arguments is not an object | Send an object, not an array or a string |
-32603 | 429 | Over 120 requests in the last minute | Back off, then retry with a widening delay |
-32603 | 200 | The server could not complete the request | Retry once; if it persists the fault is not yours |
-32020 | 400 | A request declaring 2026-07-28 in params._meta without MCP-Protocol-Version, Mcp-Method, or (for tools/call, resources/read, prompts/get) Mcp-Name | Send the headers from the same values as the body |
-32022 | 400 | A protocol revision this server does not speak. data.supported lists the four it does; data.requested echoes yours | Retry with one of data.supported |
-32601 | 404 | An unknown method on a request that declares 2026-07-28 (older requests get 200) | Check the method name; server/discover lists the capabilities |
-32602 | 200 | An unknown tool, resource or prompt name | List them first and use one that exists |
When an unknown method is a 404, and when it is not#
Revision 2026-07-28 has no sessions, and it asks a server to answer an unknown method with 404 and -32601. Connect does — for a request that declares 2026-07-28 in params._meta['io.modelcontextprotocol/protocolVersion']. A request that does not declare it there (an initialize-era client, or one that only sends the header) still gets 200 with the error object: on the older transport, 404 to a POST meant *your session is gone*, and a client that receives it drops the connection and starts again from initialize.
Until 24 September 2026 an unknown method was a 404, and so was a notification this server has no use for, such as notifications/roots/list_changed. A client that sent one was told its session had ended, reconnected, and could loop through sign-in again. Both are now what the transport asks for.
A client that treats HTTP status as the whole answer will therefore record a call to a hallucinated tool as a success. Parse the body: a response containing error is a failure whatever the status line says.
Two failures that are not protocol errors#
First, a tool that runs and cannot answer returns a *result*, not an error object: content carrying a sentence, and isError: true. A missing query, or a page reference matching nothing, arrives this way. That is the MCP convention, and it exists so a model reads the explanation and corrects itself instead of the client aborting the turn.
{"jsonrpc": "2.0", "id": 12, "result": {
"content": [{"type": "text",
"text": "No public page for '/docs/nope/'. Use search_public_docs first."}],
"isError": true}}Second, a notification — a message with no id — is answered with HTTP 202 and an empty body, whether or not this server has a use for it, and so is a JSON-RPC response a client sends. There is no result and no error to read. A client that waits for a response to a notification waits forever, which looks exactly like a hung server and is not one.
Errors from the operations tools#
The operations tools answer every failure as a tool result: isError: true, a text block, and structuredContent.error with a stable code, a sentence, and — when the application itself refused — http_status, retryable and a hint. Branch on code, never on the sentence.
error.code | Meaning | What to do |
|---|---|---|
insufficient_scope | The connection was not granted the tier this operation needs. required_scope names it and _meta carries a WWW-Authenticate challenge | Reconnect and allow that permission, or ask a workspace administrator |
person_required | A step reserved for the person in Connect itself, such as approving held work | Tell the person what is waiting; do not retry |
confirmation_invalid | The token is not Connect's, belongs to another authorization, names another operation, the arguments changed, or it expired | Ask the person to confirm the request as it now stands |
invalid_arguments | path, query or body do not match the operation's schema | Read connect_describe_operation and correct the call |
unknown_operation | No operation has that id; did_you_mean lists close ids | Pick from did_you_mean or search with connect_list_operations |
not_available_through_mcp | One of the excluded operations; the message says why | Do it in Connect |
rate_limited, too_many_in_flight | A per-connection limit | Wait retry_after seconds or for a running operation to finish |
timeout | No answer within 30 seconds; the operation may still complete | Call again with the same arguments and idempotency key |
operations_disabled | The operations surface is switched off on this server for now | Use the other tools; try later |
Any other code, with http_status | The application's own refusal (for example not_found 404, subscription_required 402), with retryable and a hint | Follow hint; retry only when retryable is true, with the same idempotency key |
The header-mismatch code#
-32020 fires in three situations, all of them the same underlying problem: MCP-Protocol-Version disagreeing with the version in params._meta, Mcp-Method disagreeing with the body's method, or Mcp-Name disagreeing with the body's name or uri. The Mcp-Name header may be Base64-wrapped as =?base64?…?=, and is decoded before the comparison, so an encoded header and a plain body still match.
The reason the specification asks for this check, and the reason it is enforced here rather than logged, is that infrastructure between client and server routes on headers while the server executes on the body. If the two can disagree, a proxy and an application can be looking at different requests. Sending no optional headers at all is a valid and simpler choice.
Questions#
Should I retry a -32603 at HTTP 200?
Once, after a short pause. It means the server caught something unexpected while handling a valid request; the message is deliberately generic and carries no internal detail. If it repeats with the same arguments, the problem is not in your client.
How do I tell a rate limit from a server fault? Both are -32603.
By the HTTP status: 429 is the limit, 200 is the fault. This is one place where the transport status is the more informative half of the answer, which is why a client should keep both.
Does the server ever return a partial result?
No. A call either returns a complete result object or an error. There is no streaming, no chunked tool output and no resumable stream — the transport removed those, so there is no half-delivered state to reconcile.