API Errors

This page covers error responses from the REST API only. For known product issues and their resolutions, see Troubleshooting, and check 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, 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 is reached, see Quotas. 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. 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 and contact 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.

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:

{
  "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.

{
  "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, and treat the detail message as informational only, as its wording may change without notice.

Get Started

Core Concepts

Integrations

Production Guides

Learn More

Status Codes

Handling Errors

Debugging Authentication Errors

Deleting Resources That Are in Use

Error Response Format

Learn More

Quotas

Troubleshooting

​Status Codes

​Handling Errors

​Debugging Authentication Errors

​Deleting Resources That Are in Use

​Error Response Format

​Learn More

Quotas

Troubleshooting

Status Codes

Handling Errors

Debugging Authentication Errors

Deleting Resources That Are in Use

Error Response Format

Learn More