Developer ToolsFree referencePDF, Excel, Word export

MCP and JSON-RPC Error Codes Reference

An MCP server speaks JSON-RPC 2.0, and mixing up protocol errors with tool failures is the most common reason an agent seems confused after something goes wrong. This table separates the two so you can return the right signal.

Download:

Code or signal	Name	Layer	Meaning	Example in an ERP MCP server
-32700	Parse error	JSON-RPC	Invalid JSON was received by the server	A client sent a truncated message over the transport
-32600	Invalid Request	JSON-RPC	The JSON is not a valid request object	Missing jsonrpc or method member
-32601	Method not found	JSON-RPC	The method does not exist or is not available	Client calls a capability the server did not declare
-32602	Invalid params	JSON-RPC	Invalid method parameters	tools/call names a tool that is not in the tool list, or arguments fail the schema
-32603	Internal error	JSON-RPC	Internal JSON-RPC error in the server	Unhandled exception in the server before a tool result is built
-32000 to -32099	Server error range	JSON-RPC	Reserved for implementation defined server errors	Custom code for ERP connection pool exhausted
-32002	Resource not found	MCP	Code used by MCP for a resource that cannot be found	resources/read for a document URI that does not exist
isError: true	Tool execution error	MCP	A tool result with isError set reports a failure the model can see and react to	ERP returned 422 closed period, returned as readable text so the model can explain it
error object	Protocol error	MCP	A JSON-RPC error response for problems with the request itself, not the tool work	Unknown tool name or malformed arguments
HTTP 202	Accepted	Streamable HTTP	Server accepts a notification or response that needs no reply body	Client sends notifications/initialized
HTTP 400	Bad Request	Streamable HTTP	Request is invalid at the transport level, for example a missing session header when one is required	Client omits the Mcp-Session-Id header after initialize
HTTP 404	Not Found	Streamable HTTP	Session ID is unknown or expired, so the client should start a new session	Server restarted and lost in-memory sessions
HTTP 405	Method Not Allowed	Streamable HTTP	Server does not offer a stream for GET on the endpoint	Stateless server that only answers POST
Mcp-Session-Id	Session header	Streamable HTTP	Header a server may return on initialize and clients must send afterward	Used to bind a conversation to one ERP user context
MCP-Protocol-Version	Version header	Streamable HTTP	Header clients send after negotiation to state the protocol version in use	Server rejects versions it does not support

Codes -32700 to -32603 come from the JSON-RPC 2.0 specification. MCP specifics can change between protocol revisions, so confirm details against the revision your SDK implements.

MCP server design review

Optional: share your tool list and we will comment on error handling and permissions.

Optional. The tool and every export work without this. No spam.

How to use it

Find the code or situation you are handling and check the layer column. JSON-RPC rows describe malformed messages and unknown methods. MCP rows describe what happens when a tool runs but the work fails. Streamable HTTP rows cover the transport. Use the ERP example column to map each case to a realistic situation, then apply it to your server's exception handling. Export to Excel for a design review.

Protocol error versus tool error

If the request itself is wrong, such as an unknown tool name or arguments that break the input schema, return a JSON-RPC error. If the request was valid but the ERP refused the work, return a normal tool result with isError set and a plain-language message. This matters because the model sees tool results and can adapt, while protocol errors are usually handled by the client application and may never reach the model in a useful form.

Unknown tool or bad schema: JSON-RPC error -32602
ERP says period closed: tool result with isError true
Server bug before any tool runs: -32603
Expired HTTP session: 404, client reinitializes

Writing messages the model can use

A tool error should say what happened, what the model can do next and what it must not do. 'Order 41822 is on credit hold, ask the user to release it in the ERP' is better than 'Error 500'. Strip stack traces, connection strings and internal table names before returning text, since the content can be shown to users and stored in conversation logs.

Common mistakes

Developers raise exceptions for ERP business rule failures, so the client shows a generic failure and the model retries blindly. Others return success text that hides the failure. A third mistake is leaking raw SQL errors. Decide a small set of error categories, such as not found, not permitted, validation and temporary, and map every ERP response into them.

Frequently Asked Questions

What does error -32602 mean in MCP?

It is the JSON-RPC Invalid params code. In MCP servers it is commonly used when a tools/call request names an unknown tool or the arguments do not satisfy the tool schema. It signals a problem with the request, not with the ERP work.

When should I use isError instead of a JSON-RPC error?

Use isError in a normal tool result when the tool ran but failed, for example the ERP rejected the transaction. The model receives that text and can react. Use a JSON-RPC error when the request itself is invalid.

Why does my MCP client get 404 after the server restarts?

With Streamable HTTP, a server that tracks sessions returns 404 for a session ID it no longer knows. The client is expected to start a new session with an initialize request. Servers that keep sessions only in memory lose them on restart.

Can I define my own JSON-RPC error codes?

Yes, the range -32000 to -32099 is reserved for implementation defined server errors. Keep a documented list, map each to a clear message, and avoid reusing codes the specification already defines.

Netray builds MCP servers and agents on top of ERP data with read-only defaults and clear error behavior. We can review your server design if you want a second opinion.

Talk to an Expert Explore More Free Tools

Related Tools

Developer Tools

More Developer Tools tools

See all

Back to All Tools