Reading Errors in the Wire

Not every request succeeds. When something fails, JSON-RPC sends back an error object instead of a result, and reading it is your fastest path to a fix.

An error response keeps the request id but swaps result for an error object holding a code and a message.

Each error carries a numeric code. Standard JSON-RPC codes are negative numbers, and a handful show up again and again on the wire.

Code -32700 means the server could not even parse your JSON. Usually a stray comma or broken quote broke the message itself.

Code -32601 says the method name does not exist. Check for a typo or a method the server never advertised, like toolz/list.

Code -32602 flags bad params: a missing argument or the wrong type. The method exists, but the inputs you sent do not fit.

Code -32603 is the server's catch-all internal error. The request was fine, but something blew up while handling it.

The code tells you the category; the message tells you the story. Always read it, since servers often add the exact field or reason that failed.

Errors may also carry a data field with extra structured detail, like which parameter was rejected. Great for debugging when it is present.

A JSON-RPC error means the protocol itself failed. A tool that runs but returns isError stays a normal result, so do not confuse the two.

Build the habit: read the code to classify, read the message to localize, then check data for the exact culprit. Most MCP bugs fall fast this way.

You sent a valid method but with a missing argument. Which error code fits?

You can now read failures fluently: an error object holds a code, a message, and sometimes data. Code classifies, message explains, and data pinpoints the cause.