Error handling

Overview

API Gateway returns standardized error responses for MCP endpoint calls in two formats: protocol errors (gateway-level) and tool execution errors (target API). Authorization-specific errors (401 and 403) are described in the Authorization and Security Model.

This information is intended for developers who build or debug MCP clients.

Protocol errors (gateway-level)

When the gateway cannot process the request, for example because of an authentication failure, an invalid request, or rate limiting, it returns a protocol error response.

{
        "jsonrpc": "2.0",
        "id": "{requestId}",
        "error": {
        "code": -32603,
        "message": "Internal error",
        "data": {
        "httpStatus": 500,
        "errorCode": "GATEWAY_INTERNAL_ERROR",
        "transactionId": "{transactionId}",
        "source": "gateway"
        }
        }
        }

Standard JSON-RPC error codes:

Table 1. Standard JSON-RPC error codes

Code	Meaning
-32700	Parse Error
-32600	Invalid Request
-32601	Method Not Found
-32602	Invalid Params
-32603	Internal Error
-32000 to -32099	Gateway-specific errors, such as authentication failures and rate limiting.

Gateway protocol errors (target API)

When the target API returns an error, API Gateway returns the response in this format:

{
        "jsonrpc": "2.0",
        "id": "{requestId}",
        "result": {
        "isError": true,
        "content": [
        {
        "type": "text",
        "text": "The requested order ORD-9999 was not found."
        }
        ],
        "structuredContent": {
        "errorCode": "RESOURCE_NOT_FOUND",
        "httpStatus": 404,
        "retryable": false,
        "transactionId": "{transactionId}",
        "source": "target",
        "details": {}
        }
        }
        }

• content: Human-readable message for the AI agent to interpret.
• structuredContent: Machine-readable details for programmatic handling.
• retryable: Indicates whether the client should retry the request.
• No internal stack traces or sensitive information are exposed.