> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.docs.relayfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors, rate limits, and retries in Relay MCP

> Relay MCP returns tool errors as MCP messages with isError true, not JSON-RPC transport errors. Auth failures are HTTP 401s. Rate limits return 429 or 503 with Retry-After.

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:

```json theme={null}
{
  "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.

> [!NOTE]
>
> 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.

> [card] [Authentication](https://mcp.docs.relayfi.com/concepts/authentication.md)
>
> Learn how to obtain audience-bound tokens and handle 401 responses.

> [card] [Result conventions](https://mcp.docs.relayfi.com/concepts/results.md)
>
> Understand dual-channel results, pagination, and cursor handling.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.