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

# API Errors

> Understand the error responses returned by the Beyond Presence API.

<Info>
  This page covers error responses from the REST API only. For known product issues and their
  resolutions, see [Troubleshooting](/production/troubleshooting), and check
  [status.bey.dev](https://status.bey.dev/) for ongoing incidents.
</Info>

Every failed request returns the appropriate HTTP status code together with a JSON body describing what went wrong.

## Status Codes

| Status | Meaning               | Typical cause                                                                                                                 |
| ------ | --------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Bad Request           | An invalid parameter value, file format, or date range was provided.                                                          |
| `401`  | Unauthorized          | The `x-api-key` header is missing or the API key is not valid.                                                                |
| `402`  | Payment Required      | Your usage limit is reached, see [Quotas](/production/concurrency). Upgrade your plan or enable usage-based billing.          |
| `403`  | Forbidden             | The resource is only available to selected customers and not accessible with your API key.                                    |
| `404`  | Not Found             | The resource does not exist, or it is not accessible with your API key.                                                       |
| `409`  | Conflict              | A resource with the same ID already exists.                                                                                   |
| `410`  | Gone                  | The feature has been permanently removed or retired.                                                                          |
| `422`  | Unprocessable Entity  | The request body or query parameters are invalid.                                                                             |
| `429`  | Too Many Requests     | Your concurrency limit has been reached, see [Quotas](/production/concurrency). Upgrade your plan or cancel ongoing sessions. |
| `500`  | Internal Server Error | An unexpected error occurred on our side.                                                                                     |
| `501`  | Not Implemented       | The requested capability is not available for your account type.                                                              |
| `503`  | Service Unavailable   | The service is temporarily at capacity.                                                                                       |

## Handling Errors

* Retry `429` and `503` responses with exponential backoff. Both are transient.
* Do not retry other `4xx` responses. They indicate a problem with the request itself, and retrying will fail the same way.
* Treat `402` and `403` as requiring an account change rather than a retry. Surface them to whoever manages your billing or plan.
* Retry `500` responses at most once or twice with backoff. If they persist, check [status.bey.dev](https://status.bey.dev/) and contact [support@beyondpresence.ai](mailto:support@beyondpresence.ai).

## Debugging Authentication Errors

Authentication failures always return `401` with one of two messages:

* `"API key is required."` when the `x-api-key` header is absent
* `"Invalid API key."` when the key is present but not recognized

To check a key without side effects, call `GET /v1/auth/verify`. It returns `204 No Content` for a valid key and `401` otherwise.

```sh theme={null}
curl --head "https://api.bey.dev/v1/auth/verify" \
  --header 'x-api-key: sk-your-api-key-here'
```

## Error Response Format

All errors carry a `detail` field. For most errors, `detail` is a single human-readable message:

```json theme={null}
{
  "detail": "Invalid API key."
}
```

Validation errors (`422`) are the exception: `detail` is a list of per-field objects describing each field that failed validation, where it was located, and why.

```json theme={null}
{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "name"],
      "msg": "Field required",
      "input": {}
    }
  ]
}
```

Some errors include additional context keys alongside `detail`, such as `avatar_id`, `agent_id`, or `creator_id`.

The API does not return machine-readable error codes. Branch your error handling on the HTTP status code, and treat the `detail` message as informational only, as its wording may change without notice.

## Learn More

<CardGroup cols={2}>
  <Card title="Quotas" icon="gauge-high" href="/production/concurrency">
    Concurrency and usage limits for your plan
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/production/troubleshooting">
    Known issues and their resolutions
  </Card>
</CardGroup>