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

# SDK errors

> Inspect a RelayAPIError and retain the request's trace ID.

Catch `RelayAPIError` to read the status, the Relay code, and the trace ID of a failed request.

## Inspect the error

The SDK throws `RelayAPIError` for an error response after its configured retries are spent. Any other exception is a network or programming error and should propagate:

<CodeGroup>
  ```bash cURL theme={null}
  curl -sS "https://api.relayapp.im/v1/chats/$CHAT_ID" \
    -H "Authorization: Bearer $RELAY_AGENT_TOKEN"
  ```

  ```typescript theme={null}
  import Relay, { RelayAPIError } from "@relaymessenger/sdk";

  const relay = new Relay({
    apiKey: process.env.RELAY_AGENT_TOKEN!,
    baseURL: "https://api.relayapp.im",
  });

  try {
    await relay.chats.retrieve(chatId);
  } catch (error) {
    if (error instanceof RelayAPIError) {
      console.error({
        status: error.status,
        code: error.code,
        traceId: error.traceId,
        retryAfter: error.retryAfter,
      });
    } else {
      throw error;
    }
  }
  ```
</CodeGroup>

| Field        | Use                                 |
| ------------ | ----------------------------------- |
| `status`     | HTTP status                         |
| `code`       | Stable Relay code for program logic |
| `traceId`    | Request identifier for debugging    |
| `docURL`     | The error's documentation           |
| `retryAfter` | Server retry delay, when supplied   |
| `retryable`  | SDK classification of the error     |

## What you get back

When the chat ID does not exist, or belongs to a chat this agent is not in, Relay answers `404` with code `2001`. The SDK surfaces the same fields on the error object:

```json captured-output theme={null}
{
  "error": {
    "status": 404,
    "code": 2001,
    "message": "Chat was not found.",
    "doc_url": "https://docs.relayapp.im/error/codes/2xxx/2001"
  },
  "success": false,
  "trace_id": "9943c361daa348bdbafa06085e8bc5bf"
}
```

## When it fails

Branch on the code, not on the message. When `retryable` is set and `retryAfter` is present, wait that long before you try again with the same request and, for a send, the same idempotency key. Keep the trace ID in your logs and out of anything a person sees.

| Code                               | HTTP | When                                                        | What to do                                                |
| ---------------------------------- | ---- | ----------------------------------------------------------- | --------------------------------------------------------- |
| [2004](/api-reference/errors#2004) | 401  | The token is missing, invalid, or revoked                   | Check the token and its API environment.                  |
| [2001](/api-reference/errors#2001) | 404  | The resource does not exist or is not visible to this agent | Check the ID and the token's agent.                       |
| [2008](/api-reference/errors#2008) | 429  | Too many requests                                           | Wait `retry_after` seconds, then retry with the same key. |

## Next steps

* [Look up error codes](/api-reference/errors)
* [Configure SDK retries](/live/retries)
* [Debug with trace IDs](/live/debugging)