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.
Status Codes
Handling Errors
- Retry
429and503responses with exponential backoff. Both are transient. - Do not retry other
4xxresponses. They indicate a problem with the request itself, and retrying will fail the same way. - Treat
402as 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
403as a permissions problem. Check that the resource belongs to your account and that you use the right API key. - Retry
500responses at most once or twice with backoff. If they persist, check status.bey.dev and contact 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 returns503. This error is transient. Retry with exponential backoff, and check status.bey.dev if the error persists.
Debugging Authentication Errors
Authentication failures always return401 with one of two messages:
"API key is required."when thex-api-keyheader is absent"Invalid API key."when the key is present but not recognized
GET /v1/auth/verify. It returns 204 No Content for a valid key and 401 otherwise.
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.
detail message names the agent or video that still uses the resource.
Error Response Format
All errors carry adetail field. For most errors, detail is a single human-readable message:
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 message as informational only, as its wording may change without notice.
Learn More
Quotas
Concurrency and usage limits for your plan
Troubleshooting
Known issues and their resolutions