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

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

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.

Get Started

Core Concepts

Integrations

Production Guides

Learn More

Status Codes

Handling Errors

Debugging Authentication Errors

Error Response Format

Learn More

Quotas

Troubleshooting

​Status Codes

​Handling Errors

​Debugging Authentication Errors

​Error Response Format

​Learn More

Quotas

Troubleshooting

Status Codes

Handling Errors

Debugging Authentication Errors

Error Response Format

Learn More