# MCP and JSON-RPC Error Codes Reference > Source: https://netray.co/tools/mcp-and-json-rpc-error-codes-reference > Publisher: Netray (netray.co), AI and integration engineering for ERP and manufacturing systems. > Section: Free Tools ## Short answer A lookup table of JSON-RPC 2.0 error codes and how an MCP server should signal protocol errors versus tool failures. ## Category developer ## Audience - MCP server developer - AI engineer - Integration developer ## Tool **Kind:** worksheet **Mode:** reference **Columns:** #### Code or signal **Key:** code **Type:** text #### Name **Key:** name **Type:** text #### Layer **Key:** layer **Type:** text #### Meaning **Key:** meaning **Type:** text #### Example in an ERP MCP server **Key:** erp **Type:** text **Rows:** #### Parse error **Code:** -32700 **Layer:** JSON-RPC **Meaning:** Invalid JSON was received by the server **Erp:** A client sent a truncated message over the transport #### Invalid Request **Code:** -32600 **Layer:** JSON-RPC **Meaning:** The JSON is not a valid request object **Erp:** Missing jsonrpc or method member #### Method not found **Code:** -32601 **Layer:** JSON-RPC **Meaning:** The method does not exist or is not available **Erp:** Client calls a capability the server did not declare #### Invalid params **Code:** -32602 **Layer:** JSON-RPC **Meaning:** Invalid method parameters **Erp:** tools/call names a tool that is not in the tool list, or arguments fail the schema #### Internal error **Code:** -32603 **Layer:** JSON-RPC **Meaning:** Internal JSON-RPC error in the server **Erp:** Unhandled exception in the server before a tool result is built #### Server error range **Code:** -32000 to -32099 **Layer:** JSON-RPC **Meaning:** Reserved for implementation defined server errors **Erp:** Custom code for ERP connection pool exhausted #### Resource not found **Code:** -32002 **Layer:** MCP **Meaning:** Code used by MCP for a resource that cannot be found **Erp:** resources/read for a document URI that does not exist #### Tool execution error **Code:** isError: true **Layer:** MCP **Meaning:** A tool result with isError set reports a failure the model can see and react to **Erp:** ERP returned 422 closed period, returned as readable text so the model can explain it #### Protocol error **Code:** error object **Layer:** MCP **Meaning:** A JSON-RPC error response for problems with the request itself, not the tool work **Erp:** Unknown tool name or malformed arguments #### Accepted **Code:** HTTP 202 **Layer:** Streamable HTTP **Meaning:** Server accepts a notification or response that needs no reply body **Erp:** Client sends notifications/initialized #### Bad Request **Code:** HTTP 400 **Layer:** Streamable HTTP **Meaning:** Request is invalid at the transport level, for example a missing session header when one is required **Erp:** Client omits the Mcp-Session-Id header after initialize #### Not Found **Code:** HTTP 404 **Layer:** Streamable HTTP **Meaning:** Session ID is unknown or expired, so the client should start a new session **Erp:** Server restarted and lost in-memory sessions #### Method Not Allowed **Code:** HTTP 405 **Layer:** Streamable HTTP **Meaning:** Server does not offer a stream for GET on the endpoint **Erp:** Stateless server that only answers POST #### Session header **Code:** Mcp-Session-Id **Layer:** Streamable HTTP **Meaning:** Header a server may return on initialize and clients must send afterward **Erp:** Used to bind a conversation to one ERP user context #### Version header **Code:** MCP-Protocol-Version **Layer:** Streamable HTTP **Meaning:** Header clients send after negotiation to state the protocol version in use **Erp:** Server rejects versions it does not support **Notes:** 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. ## Content **Intro:** 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. **Sections:** #### How to use it **Body:** 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 **Body:** 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. **Bullets:** - 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 **Body:** 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 **Body:** 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. **Cta:** 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. **Faq:** #### What does error -32602 mean in MCP? **Answer:** 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? **Answer:** 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? **Answer:** 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? **Answer:** 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. ## Search terms mcp error codes, json-rpc error codes, -32602 invalid params mcp, mcp isError tool result, mcp server error handling, json rpc 2.0 error list, mcp streamable http session id error, model context protocol errors --- Talk to an engineer: https://netray.co/contact?intent=erp_ai | Machine catalog: https://netray.co/agent/catalog.json