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

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


## Related topics

- [Beyond Presence REST API](/concepts/api/index.md)
- [Troubleshooting](/production/troubleshooting.md)
- [Concurrency & Quotas](/production/concurrency.md)
- [Changelog](/learn/changelog.md)
- [Delete External API Configuration](/api-reference/agents-external-apis/delete-external-api-configuration.md)


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