Two Ways for a Request to Fail
A failed request does not get to invent its own vocabulary. MCP 2026-07-28 fixes a small set of numbers, splits every failure into one of two channels, and puts a firm list of numbers permanently out of reach. Tell a protocol error from a tool execution error and know which channel a server must use for a given failure. Name the three MCP-reserved error codes, -32020, -32021, and -32022, and the data each one carries. Apply the 2026-07-28 error code allocation policy: the legacy sub-range, the reserved sub-range, and where an application-defined code belongs. Map a JSON-RPC error code to the HTTP status a Streamable HTTP server must return alongside it. Explain why -32002 and -32042 must never be emitted by a 2026-07-28 implementation, and what replaced each one. A server that has never thought hard about failure tends to invent its own error vocabulary as it goes. A missing argument gets one ad hoc code, a downstream timeout gets another, a permission problem becomes a made up string buried in a message field. None of that travels. A client built by a different team has no way to know what a number some other server picked on a Tuesday actually means, and two servers that both reach for the same convenient number, say -32001, can mean two unrelated things…
Two Ways for a Request to Fail: A failed request does not get to invent its own vocabulary. MCP 2026-07-28 fixes a small set of numbers, splits every failure…
This free lesson is part of the AI Engineering from Scratch curriculum. Read the full explanation, run the lesson code, and verify the result in the interactive reader or from the repository source.
Browse the complete course catalog or open this lesson on GitHub.