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

# Errors

> The response envelope and status codes every API endpoint uses.

## What is this?

Every response — success or failure — uses the same envelope, so your code can handle results the same way for every endpoint.

## What can I do here?

* Recognize a successful response
* Read the error shape and status codes
* Diagnose the most common failures

## How to use it

### Success

```json theme={null}
{
  "success": true,
  "data": { "id": "ct_1", "name": "John Doe" },
  "message": "Contact created successfully"
}
```

List endpoints also return `pagination` and `total` alongside `data`.

### Failure

```json theme={null}
{
  "success": false,
  "error": "Short error reason",
  "message": "Human-readable detail"
}
```

### Status codes

| Status | Meaning                                                                                          |
| ------ | ------------------------------------------------------------------------------------------------ |
| `200`  | Success                                                                                          |
| `400`  | Missing or invalid parameters                                                                    |
| `401`  | Missing or invalid API key (or an expired session, for session endpoints)                        |
| `403`  | Authenticated but not allowed — wrong permissions, or a resource that belongs to another tenant  |
| `429`  | Rate limited — wait for the `Retry-After` seconds. See [Rate limits](/api-reference/rate-limits) |
| `500`  | Unexpected server error                                                                          |

Individual endpoints may document extra status codes, such as `404` for a resource that isn't found. Check the endpoint's own page.

## Troubleshooting / Technical Notes

* **`400` with a message naming a parameter.** That parameter is required or invalid. Check the request body on the endpoint page.
* **`401` right after generating a key.** Make sure you copied the whole key and sent it in a header. See [Authentication](/api-reference/authentication).
* **`403` on a Workspace endpoint.** The `channelId` you passed isn't owned by the key's account. Use **List channels** to find valid IDs.
* **"No channel found for this user."** Pass a `channelId`, or create a channel first.

## Related docs

* [Introduction](/api-reference/introduction)
* [Authentication](/api-reference/authentication)
* [Rate limits](/api-reference/rate-limits)