> ## 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.

# Error Codes

> Handle Relay API errors by HTTP status, numeric code, and trace ID.

Every Relay API error uses the same JSON envelope.

```json theme={null}
{
  "error": {
    "status":404,
    "code":2001,
    "message":"Resource not found.",
    "doc_url":"https://docs.relayapp.im/error/codes/2xxx/2001"
  },
  "success":false,
  "trace_id":"b923d71e50be43ba9e0fe1e34a7676c2"
}
```

Use `error.code` for program logic. Record `trace_id` when diagnosing a failed request.

## Envelope fields

| Field               | Use                                |
| ------------------- | ---------------------------------- |
| `error.status`      | HTTP status                        |
| `error.code`        | Stable numeric program key         |
| `error.message`     | Readable diagnostic explanation    |
| `error.doc_url`     | Direct link to the code page       |
| `error.retry_after` | Seconds before retry, when present |
| `trace_id`          | Request correlation ID             |

## Error code ranges

| Range | Category                                         | Default retry rule                        |
| ----- | ------------------------------------------------ | ----------------------------------------- |
| 1xxx  | Request errors                                   | Fix the request before retrying           |
| 2xxx  | Authentication, resource, state, or limit errors | Follow the code-specific guidance         |
| 3xxx  | Relay server errors                              | Retry only when the command is idempotent |

## 1xxx request errors

| Code                           | Meaning                             |
| ------------------------------ | ----------------------------------- |
| [1004](/error/codes/1xxx/1004) | Mentioned Handle is not in the Chat |
| [1005](/error/codes/1xxx/1005) | Request or current state is invalid |

## 2xxx resource errors

| Code                           | Meaning                        |
| ------------------------------ | ------------------------------ |
| [2001](/error/codes/2xxx/2001) | Resource not found             |
| [2003](/error/codes/2xxx/2003) | Permission denied              |
| [2004](/error/codes/2xxx/2004) | Authentication required        |
| [2005](/error/codes/2xxx/2005) | Attachment owner unavailable   |
| [2006](/error/codes/2xxx/2006) | Invalid or unsupported content |
| [2007](/error/codes/2xxx/2007) | Attachment is not ready        |
| [2008](/error/codes/2xxx/2008) | Request was rate limited       |
| [2015](/error/codes/2xxx/2015) | Mentioned Handle left the Chat |
| [2023](/error/codes/2xxx/2023) | Mentions require a group Chat  |
| [2025](/error/codes/2xxx/2025) | Blocked Handle not found       |
| [2026](/error/codes/2xxx/2026) | Handle is blocked              |

## 3xxx server errors

| Code                           | Meaning                       |
| ------------------------------ | ----------------------------- |
| [3006](/error/codes/3xxx/3006) | Unexpected Relay server error |

## Related

* [Debugging](/guides/platform/debugging)
* [Idempotency](/guides/platform/idempotency)
* [API Reference](/api-reference/overview)