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

# Errors

> Status codes, the error envelope, and validation error shape

## The error envelope

Every error response from `/api/v1/` is a JSON object with a single top-level `error` key whose value is
a human-readable string:

```json theme={null}
{
  "error": "Invalid or expired API key."
}
```

This is consistent across authentication failures, permission checks, throttling, not-found, and
method-not-allowed responses — you can always read `body.error` for a displayable message.

## Status codes

| Status                      | Meaning                                                                                                                             |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `200 OK` / `201 Created`    | Success. `201` on resource creation.                                                                                                |
| `204 No Content`            | Success with no body (e.g. a `DELETE`).                                                                                             |
| `400 Bad Request`           | Invalid input — see [validation errors](#validation-errors) below.                                                                  |
| `401 Unauthorized`          | Missing, malformed, or revoked API key.                                                                                             |
| `403 Forbidden`             | Valid key, but it lacks the required [scope](/authentication#scopes), or the workspace trial has expired (writes become read-only). |
| `404 Not Found`             | The resource doesn't exist, or isn't in your workspace.                                                                             |
| `405 Method Not Allowed`    | The endpoint doesn't support that HTTP method.                                                                                      |
| `429 Too Many Requests`     | [Rate limit](/rate-limits) exceeded. Includes a `Retry-After` header.                                                               |
| `500 Internal Server Error` | An unexpected server error — see [below](#server-errors).                                                                           |

## Validation errors

Field-level validation errors (`400 Bad Request`) are the one intentional exception to the single-`error`
envelope. They follow Django REST Framework's field-keyed convention — a map of field name to a list of
messages, so you can surface errors next to the right input:

```json theme={null}
{
  "phone_number": ["This field is required."],
  "template_name": ["No approved template with this name exists in your workspace."]
}
```

Non-field errors appear under `non_field_errors`:

```json theme={null}
{
  "non_field_errors": ["Either `text` or `template_name` must be provided, not both."]
}
```

<Tip>
  When parsing a `400`, check for the `error` key first; if it's absent, treat the body as a
  field → messages map.
</Tip>

## Server errors

A `500` never leaks internal detail. The full exception (including stack trace) is captured server-side;
the client always receives a fixed, parsable body:

```json theme={null}
{
  "error": "An unexpected error occurred. Please try again or contact support if the problem persists."
}
```

If you hit a reproducible `500`, contact support with the timestamp and endpoint — we can correlate it to
the captured exception.

<Warning>
  A request to a **completely unrouted** `/api/v1/...` path (a typo'd or non-existent endpoint) returns
  Django's HTML 404 page rather than the JSON envelope above. Always confirm your path matches an endpoint
  in the [API Reference](/api-reference) — every *routed* endpoint returns JSON, but an unknown path does
  not.
</Warning>