Errors, rate limits, and retries in Relay MCP

Relay MCP separates transport-level failures from tool-level failures. Authentication problems surface as HTTP status codes on the request itself, while business logic and validation issues are returned as MCP tool errors inside a successful JSON-RPC response. Underlying error details from upstream services are never echoed back to the agent.

MCP tool errors

When a tool call fails for a recoverable reason, the server returns a JSON-RPC success response containing an MCP error result. The agent can read the message and continue the conversation:

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "Authentication is required."
      }
    ]
  }
}

This pattern applies to validation, missing resources, and pagination problems. It is distinct from JSON-RPC transport errors such as parse failures or method-not-found responses.

Error conditions and messages

Condition	Message
No `Authorization` header reached the tool	`Authentication is required.`
Resource missing or not accessible	`<Resource> not found or not accessible.`
Invalid pagination cursor	`The pagination cursor is invalid. Restart pagination without a cursor and keep the same pageSize for subsequent pages.`
Any other upstream failure	A generic failure message (detail not echoed)

Authentication failures

If the token is missing, malformed, or unverifiable, the server returns HTTP 401 Unauthorized with a WWW-Authenticate header. This is a transport error, not a tool error. Your client must re-authorize before retrying.

A 401 means re-authorize. Re-read the discovery document at /.well-known/oauth-protected-resource/mcp if necessary, then obtain a new token. Do not retry the same request with the same token.

Rate limits

The server may return these retryable status codes:

Status	Meaning	Action
`429 Too Many Requests`	Rate limit exceeded	Retry after the delay specified in the `Retry-After` header
`503 Service Unavailable`	Temporary unavailability	Retry after the delay specified in the `Retry-After` header

Both codes are retryable. Honor the Retry-After value before sending the next request.

Authentication

Learn how to obtain audience-bound tokens and handle 401 responses.

Result conventions

Understand dual-channel results, pagination, and cursor handling.

Get Started

Concepts

Errors, rate limits, and retries in Relay MCP

MCP tool errors

Error conditions and messages

Authentication failures

Rate limits

Authentication

Result conventions

​MCP tool errors

​Error conditions and messages

​Authentication failures

​Rate limits

Authentication

Result conventions

MCP tool errors

Error conditions and messages

Authentication failures

Rate limits