Connect by JBRH Open Connect

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.

Status
Available What this means
Audience
developer
Last verified
Product version
6.3.2

The codes#

CodeHTTPCauseWhat to do
-32700400The body is not valid JSONFix the serialiser. Retrying sends the same broken bytes
-32600403A present Origin header is not recognisedSend no Origin from a non-browser client, or call from an allowed origin
-32600413The request body is over 256 KiBSplit the call. No documentation tool needs an argument that large
-32600400A JSON-RPC batch was sentSend one message per request; batches are refused outright
-32600400An unsupported protocol version was asked forRead error.data.supported and pick one of the four listed revisions
-32020400A header disagrees with the request bodyMake the header match, or send neither
-32600400The message has no method and is not a responseSend a JSON-RPC request, notification or response
-32601200The JSON-RPC method does not existCheck the spelling against tools/list, resources/list, prompts/list
-32601200The tool, resource or prompt named does not existList them and use a real name; the method itself was valid
-32602200params or arguments is not an objectSend an object, not an array or a string
-32603429Over 120 requests in the last minuteBack off, then retry with a widening delay
-32603200The server could not complete the requestRetry once; if it persists the fault is not yours
-32020400A request declaring 2026-07-28 in params._meta without MCP-Protocol-Version, Mcp-Method, or (for tools/call, resources/read, prompts/get) Mcp-NameSend the headers from the same values as the body
-32022400A protocol revision this server does not speak. data.supported lists the four it does; data.requested echoes yoursRetry with one of data.supported
-32601404An unknown method on a request that declares 2026-07-28 (older requests get 200)Check the method name; server/discover lists the capabilities
-32602200An unknown tool, resource or prompt nameList 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.codeMeaningWhat to do
insufficient_scopeThe connection was not granted the tier this operation needs. required_scope names it and _meta carries a WWW-Authenticate challengeReconnect and allow that permission, or ask a workspace administrator
person_requiredA step reserved for the person in Connect itself, such as approving held workTell the person what is waiting; do not retry
confirmation_invalidThe token is not Connect's, belongs to another authorization, names another operation, the arguments changed, or it expiredAsk the person to confirm the request as it now stands
invalid_argumentspath, query or body do not match the operation's schemaRead connect_describe_operation and correct the call
unknown_operationNo operation has that id; did_you_mean lists close idsPick from did_you_mean or search with connect_list_operations
not_available_through_mcpOne of the excluded operations; the message says whyDo it in Connect
rate_limited, too_many_in_flightA per-connection limitWait retry_after seconds or for a running operation to finish
timeoutNo answer within 30 seconds; the operation may still completeCall again with the same arguments and idempotency key
operations_disabledThe operations surface is switched off on this server for nowUse the other tools; try later
Any other code, with http_statusThe application's own refusal (for example not_found 404, subscription_required 402), with retryable and a hintFollow 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.