What is JSONRPCError?
JSONRPCError is the failure counterpart to JSONRPCResponse in the MCP message exchange. It shares the same envelope fields — jsonrpc must be the literal string "2.0" and id must echo the request's id exactly — but instead of a result field it carries an error object with three sub-fields: code (a signed integer), message (a human-readable string), and an optional data field of type unknown that can hold any JSON-serializable debugging payload. This structure is defined by the JSON-RPC 2.0 specification and MCP adopts it unchanged, meaning any compliant JSON-RPC client library can parse MCP errors without custom handling. Error codes follow a strict taxonomy. The reserved range from -32700 to -32600 covers parse errors through invalid requests; -32601 signals that the requested method does not exist on the server; -32602 means the params object failed validation; -32603 indicates an unexpected internal failure. MCP servers that need to surface application-level failures — such as a tool execution timeout or a missing resource — must use codes in the -32000 to -32099 range rather than inventing arbitrary negative integers, which keeps the number space unambiguous for clients. The id field introduces an important edge case: when parsing fails before the id can be extracted, the spec requires id to be null rather than omitted entirely. SDKs that strictly deserialize JSONRPCError will reject a response whose id is absent, even though the semantics feel equivalent. Developers building custom transports or middleware should ensure they always emit the null id in that path to stay compatible with strict validators on the receiving end.
When to use
On unrecoverable protocol failures — for tool execution failures use isError:true.
When NOT to use
For validation errors in tool calls — return them in CallToolResult.
Notes
Null id vs absent id matters
JSON-RPC 2.0 requires id to be null (not absent) when the server cannot determine the original request id, such as during a parse failure. Many client SDKs — including the official MCP TypeScript SDK — use discriminated-union type guards that check for the presence of the error key rather than the id value, so this distinction usually does not cause a runtime crash. However, strict schema validators like Zod will reject an absent id field because the schema marks it required, producing a confusing secondary error that masks the original failure.
Custom error codes stay in -32000 range
Application-level errors from MCP tool handlers, resource reads, or prompt renders must use integer codes in the inclusive range -32000 to -32099. Using codes outside this range — for example, positive integers or codes below -32099 — is technically valid JSON-RPC but breaks the implicit contract that clients use to distinguish transport/protocol errors from server-logic errors. Some client implementations treat any code outside the reserved ranges as unknown and swallow the error silently instead of surfacing it to the caller.
data field is untyped by design
The error.data field is typed as unknown in the MCP schema, giving server authors freedom to attach stack traces, validation failure details, or structured context objects. This flexibility is intentional but creates a security surface: avoid embedding internal file paths, environment variable values, or raw exception messages in data when the transport is exposed over a network. Treat data as a developer-only debugging aid and gate its population behind an environment flag in production deployments.
Distinguishing from JSONRPCResponse at runtime
JSONRPCError and JSONRPCResponse share the same id and jsonrpc fields, so deserialization code must branch on the presence of the error key rather than the absence of result. The MCP TypeScript SDK uses a type guard isJSONRPCError(msg) that checks for error !== undefined after a base parse. If your transport layer deserializes into a generic object before routing, ensure the branch happens before you attempt to access msg.result, because a well-formed error response will have result as undefined and accessing nested properties on it will throw.
message field is for humans, not machines
The spec defines error.message as a short human-readable description and explicitly discourages using it as a machine-parseable status string. Client code that switches on the message string for control flow will break across MCP server versions or different server implementations that phrase the same error differently. Use error.code for programmatic branching and reserve message for logging and developer-facing UI only.
Fields
| Field | Type | Required | Purpose |
|---|---|---|---|
| jsonrpc | '2.0' | yes | Protocol identifier. |
| id | string | number | null | yes | Matches request id (null if parse error). |
| error.code | number | yes | Numeric error code. |
| error.message | string | yes | Short human description. |
| error.data | unknown? | no | Optional structured details. |
Examples
Method not found
{
"jsonrpc": "2.0", "id": 99,
"error": { "code": -32601, "message": "Method not found" }
}Common mistakes
❌ Surfacing tool failures as -32603
✅ Tool failures belong in CallToolResult with isError:true.