> ## Documentation Index
> Fetch the complete documentation index at: https://docs.staging.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:

```bash cURL theme={null}
curl -sS "https://api.staging.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.staging.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;
  }
}
```

| 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](https://docs.staging.relayapp.im/api-reference/errors.md#2004) | 401 | The token is missing, invalid, or revoked | Check the token and its API environment. |
| [2001](https://docs.staging.relayapp.im/api-reference/errors.md#2001) | 404 | The resource does not exist or is not visible to this agent | Check the ID and the token's agent. |
| [2008](https://docs.staging.relayapp.im/api-reference/errors.md#2008) | 429 | Too many requests | Wait `retry_after` seconds, then retry with the same key. |

## Next steps

* [Look up error codes](https://docs.staging.relayapp.im/api-reference/errors.md)
* [Configure SDK retries](https://docs.staging.relayapp.im/live/retries.md)
* [Debug with trace IDs](https://docs.staging.relayapp.im/live/debugging.md)


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