Errors

MCP clients can see three kinds of error. They arrive in different places, so handle each one where it appears.

HTTP errors

The request never reaches the tool. The body is a JSON-RPC error with code -32000.

Status	When	What to do
401	No token, or the token is invalid or expired	Follow the WWW-Authenticate challenge; see Authorization
405	GET or DELETE on the endpoint	Send POST. The endpoint has no SSE stream and no sessions
429	A quota limit is exceeded	Wait Retry-After seconds; see Quotas

Tool errors

The tool ran and failed, or was refused before it ran. Either way the response is a normal 200 with a tools/call result that has isError: true and the reason as text. Errors the MCP SDK raises before the tool's own code runs — arguments that do not match the input schema, or an unknown tool name — arrive the same way, with text that starts with MCP error -32602:. They are still tool results, not JSON-RPC error objects, so a client has to look at result.isError rather than at error.code.

An error from the tool itself, for check_availability with { "domains": ["!!!"] }:

{
    "result": {
        "content": [{ "type": "text", "text": "Invalid domain format" }],
        "isError": true
    },
    "jsonrpc": "2.0",
    "id": 4
}

An error from input validation, for compare_prices with { "domain": "kettlory" }:

{
    "result": {
        "content": [
            {
                "type": "text",
                "text": "MCP error -32602: Input validation error: Invalid arguments for tool compare_prices: A full domain name is required at domain"
            }
        ],
        "isError": true
    },
    "jsonrpc": "2.0",
    "id": 1
}

Message	Cause
MCP error -32602: Input validation error: Invalid arguments for tool <name>: …	The arguments do not match the tool's input schema — a missing field, a value out of range, a domain without a dot. The text ends with the field, for example Too big: expected array to have <=20 items at domains
Invalid domain format	Nothing is left of the input once characters that cannot appear in a domain name are removed, or the name has a TLD NameBeta does not know. Other stray characters are removed silently rather than rejected; see check_availability
MCP error -32602: Tool <name> not found	The tool name is misspelled or does not exist
Any other message	The lookup behind the tool failed, for example a WHOIS or DNS server that did not answer; it may succeed if retried later

Each tool's page lists the errors specific to it. Whether a failed call still counts against your quota is covered under How calls are counted.

Malformed requests

A request the MCP transport cannot accept is rejected with a 4xx status before any tool runs — for example 406 when the Accept header does not list both application/json and text/event-stream, or a JSON-RPC parse error (-32700) for a body that is not valid JSON-RPC. Batched (array) JSON-RPC requests are rejected with 400 and the JSON-RPC error -32600, as the MCP specification dropped batching in its 2025-06-18 revision; send one request per POST. Fix the request rather than retrying it. Endpoint and transport describes the requests the endpoint accepts.