> ## 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 Beyond Presence REST API HTTP status codes and how to debug error responses.

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

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, the resource is not yet available, or the resource you tried to delete is still in use. |
| `401` | Unauthorized | The `x-api-key` header is missing or the API key is not valid. |
| `402` | Payment Required | Your usage limit or avatar slot limit is reached, see [Quotas](https://docs.bey.dev/production/concurrency.md), or the feature is not available on your plan. Upgrade your plan or enable usage-based billing. |
| `403` | Forbidden | The resource is not accessible or editable 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](https://docs.bey.dev/production/concurrency.md). 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, or a service the API depends on is unavailable or timed out. |

## 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` as requiring a plan change rather than a retry. It covers every plan-gated limit and feature. Surface it to whoever manages your billing or plan.
* Treat `403` as a permissions problem. Check that the resource belongs to your account and that you use the right API key.
* 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).

## Using Avatars That Are Not Yet Available

`POST /v1/session`, `POST /v1/livekit-rooms`, and `POST /v1/videos` return `400` when the avatar is not yet available, for example while it is still training. Studio refuses to start calls with the avatar the same way. For sessions and calls, the `detail` message names the avatar and its current state. Wait until the avatar is available, then retry the request.

## Debugging Service Outages

When a service the API depends on is down or times out, the API returns `503`. This error is transient. Retry with exponential backoff, and check [status.bey.dev](https://status.bey.dev/) if the error persists.

## 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'
```

## Deleting Resources That Are in Use

The API refuses to delete a resource that something else still depends on and returns an error instead:

* **Avatar**: An agent uses the avatar, or a video that is still pending or processing uses it. Assign a different avatar to the agent, or delete the video first.
* **External API configuration**: An agent uses the configuration as its LLM. Change the agent's LLM first.
* **Knowledge file**: An agent references the file. Detach the file from the agent first.

The `detail` message names the agent or video that still uses the resource.

## 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": {}
    }
  ]
}
```

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

## Learn More

> [card] [Quotas](https://docs.bey.dev/production/concurrency.md)
>
> Concurrency and usage limits for your plan

> [card] [Troubleshooting](https://docs.bey.dev/production/troubleshooting.md)
>
> Known issues and their resolutions


## Related topics

- [Beyond Presence REST API](https://docs.bey.dev/concepts/api/index.md)
- [Troubleshooting](https://docs.bey.dev/production/troubleshooting.md)
- [Concurrency & Quotas](https://docs.bey.dev/production/concurrency.md)
- [Changelog](https://docs.bey.dev/learn/changelog.md)
- [Custom Avatars](https://docs.bey.dev/concepts/avatars/custom.md)


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