Error Codes

The MCP connector surfaces failures across three layers: JSON-RPC protocol errors (in the response error field), tool-execution errors (in a normal result with isError: true), and HTTP status codes from the shared HTTP server. This page is the authoritative catalog of every code. For task-focused guidance on detecting and recovering from these layers in client code, see the Error Handling guide.

The three error layers

A single failed tools/call can fail at exactly one of three levels. Check them in order — protocol first, then tool result, then transport — because a higher-layer failure short-circuits the lower layers.

JSON-RPC protocol error codes

Protocol-level errors mean the request itself was malformed or could not be dispatched. They are returned in the error field — there is no result field. The HTTP status is still 200 (per JSON-RPC convention); the failure is encoded in the body.

-32700 through -32603 are the standard JSON-RPC 2.0 reserved codes. -32010 is a KubeMQ server-defined code shared by the JSON-RPC endpoints (/mcp, /a2a).

Error response format

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}

A parse error that occurs before the request id can be read returns "id": null:

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32700,
    "message": "Parse error"
  }
}

Authentication failures (-32010)

When JWT auth is enabled and a request to /mcp carries a missing or invalid Authorization: Bearer token, the connector returns the JSON-RPC auth code -32010 with HTTP status 200 — not HTTP 401:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32010,
    "message": "authentication required"
  }
}

Tool-execution errors (isError)

Tool-level errors are not JSON-RPC errors. The request was valid JSON-RPC and was dispatched successfully, but the underlying messaging operation failed. The response carries a normal result field with isError: true; the human-readable cause is in result.content[].text.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "Agent 'nonexistent' not found" }],
    "isError": true
  }
}

This is why robust clients check for error first, then result.isError — a successful protocol response can still describe a failed tool operation.

Common tool-execution errors

Reserved-channel rejection comes from the shared _AGENTS_. prefix guard — see Channel resolution.

HTTP status codes

For a well-formed request, the connector returns HTTP 200 even when the body contains a JSON-RPC error. Other statuses originate from the shared HTTP server layer (middleware chain) before or around tool dispatch.

Resolution order

When handling a response, evaluate the layers top-down:

1. Inspect the HTTP status. A 503 means the broker is not ready (retry with backoff); a 504 means the request timed out.
2. Check for error. A present error field is a JSON-RPC protocol failure — fix the request (or token for -32010). Do not look for result.
3. Check result.isError. If true, the tool ran but the operation failed; read the cause from result.content[0].text.
4. Otherwise the call succeeded — the payload is in result.content.

Related