Skip to main content
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

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 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 returns 503. This error is transient. Retry with exponential backoff, and check 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.

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:
Request 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.
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

Quotas

Concurrency and usage limits for your plan

Troubleshooting

Known issues and their resolutions