Error Handling

Two levels of errors

This distinction is one of the most tested concepts in the exam:

Level	Where it appears	Who handles it	Example
Protocol error	JSON-RPC error object in the response	The client/host code	Unknown method, unknown tool name, invalid cursor
Tool execution error	A normal result with isError: true	The model (it sees the error text and can retry/adjust)	API timeout, “city not found”, business-logic failure, invalid tool arguments

Caution

A failed tool execution is not a JSON-RPC error. It returns a successful JSON-RPC response whose result has isError: true and error details in content. This lets the LLM see the failure and self-correct.

flowchart TD
A[Something went wrong] --> B{Could the request even be processed?}
B -- "No: bad JSON, unknown method,<br/>unknown tool, invalid cursor" --> C[JSON-RPC error object]
C --> D[Handled by client/host code]
B -- "Yes: the tool ran but<br/>the operation failed" --> E["Result with isError: true"]
E --> F[Surfaced to the model,<br/>which can retry or adapt]

Which error path?

Tip

Since the 2025-11-25 revision, invalid tool input (arguments that fail schema validation) is reported as a tool execution error (isError: true), not a protocol error — so the model can see the validation message and fix its arguments.

Standard JSON-RPC error codes

Code	Meaning
-32700	Parse error (invalid JSON)
-32600	Invalid request
-32601	Method not found
-32602	Invalid params (e.g. unknown tool name, unknown resource, invalid cursor)
-32603	Internal error

The current spec (2026-07-28) also defines protocol-specific codes and reserves the range -32020 to -32099 for the specification itself, for example:

Code	Meaning
-32020	HeaderMismatch — HTTP MCP-Protocol-Version header disagrees with the version in _meta
-32022	UnsupportedProtocolVersionError — server does not support the requested protocol version

Note

“Resource not found” used code -32002 in older revisions; since 2026-07-28 it is reported as -32602 (Invalid params), and clients should still accept -32002 for backwards compatibility.

Example: tool execution error

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Failed to fetch weather: rate limit exceeded. Retry after 60s."
      }
    ],
    "isError": true
  }
}

Recovery strategies

• Model-driven retry — the LLM reads the error content and tries different arguments or another tool
• Timeouts — implementations should apply per-request timeouts and cancel on expiry (on stdio, cancel with notifications/cancelled; on Streamable HTTP, closing the SSE response stream is the cancellation signal)
• Graceful degradation — hosts continue working when one server fails; other servers are unaffected
• Validation first — servers validate inputs against the schema and return clear, actionable error messages

Key exam points

• Protocol errors → JSON-RPC error object; execution errors → isError: true in the result
• Execution errors are surfaced to the model so it can adapt
• Invalid tool arguments are execution errors, not protocol errors
• One misbehaving server must not take down the host or other servers

Check your knowledge

📝 Check your knowledge

1. A tool call references a tool name that doesn't exist on the server. How is this reported?

AA result with isError: true so the model can retryBA JSON-RPC error object (Invalid params, -32602)CHTTP status 404 with no bodyDA notifications/cancelled notification

2. A weather API inside a tool times out. How should the server report this?

AReturn a JSON-RPC error with code -32603BClose the connection so the client restarts the serverCReturn a successful JSON-RPC response with isError: true and the error text in contentDSend a log notification and no response

3. Why are tool execution errors returned inside a successful JSON-RPC response?

ABecause JSON-RPC has no error objectBSo the LLM can see the failure details and adjust its next attemptCTo avoid HTTP status codes other than 200DBecause clients ignore JSON-RPC error objects

4. The model calls a tool with arguments that fail the tool's input schema validation. Per current spec guidance, this is a...

AProtocol error with code -32700BProtocol error with code -32601CTool execution error (isError: true) so the model can fix its argumentsDReason to terminate the connection

5. Which JSON-RPC code means "Method not found"?

A-32700B-32601C-32602D-32603

6. A server does not support the protocol version a request declares. What does the current (2026-07-28) spec say it must return?

AAn isError: true resultBUnsupportedProtocolVersionError, JSON-RPC code -32022CHTTP 500 with an empty bodyDJSON-RPC code -32002