Skip to main content
What each runtime error means and whether to retry it. These are the errors your app gets from runtime.xenovia.io; errors from the management API are in the API reference. The runtime answers the same situation with the same status on every route, and writes the body in the format of the API you called. Nothing in a body names the provider or the route taken. That detail is in the X-Xenovia-* response headers, such as X-Xenovia-Provider and X-Xenovia-Trace-Id.

OpenAI-compatible routes

/{agent_id}/v1/chat/completions and /{agent_id}/v1/responses return the OpenAI error object. param and code can be null:
OpenAI SDKs raise these as their usual typed errors (401 → AuthenticationError, 429 → RateLimitError, and so on).

Anthropic-compatible routes

/{agent_id}/v1/messages and /{agent_id}/v1/messages/count_tokens return the Anthropic error object. The request_id matches the request-id response header, and is your x-request-id when you sent one:
The Anthropic SDKs raise these as their usual typed errors (AuthenticationError, RateLimitError, OverloadedError, and so on).

Runtime status codes

Any other error the provider returns keeps the provider’s status. On the OpenAI-compatible routes its type, code, and param stay inside the same error object. A 401, 402, or 403 from the provider means the credential saved on the agent was refused, not yours. The runtime answers it as a 502 so your app does not read it as its own key failing, and the message says nothing about what the provider returned. Fix the provider credential on the agent. The SDK’s POST /v1/execute and the coding-agent hook endpoints return their own bodies, with the same status codes. A hook still answers 200 with its decision. See the Python SDK.

Streams that fail midway

A stream that fails after the first chunk can’t change its status, so it ends with one error event. On the OpenAI-compatible routes the event is data: {"error": {"message": "...", "type": "...", "code": "..."}}, and code is a string or null. On the Anthropic-compatible routes it is event: error followed by the Anthropic error object.

Blocks are not errors

A policy block, a Neon block and a policy escalation return 200 with a refusal, not an error. See What a block looks like to your app. Only the steps of a simulation run still get a 403 for a block.

Fallback providers

For an agent with fallback providers, the runtime returns 503 when every provider it tried failed with an error the agent fails over on. It sets Retry-After. On the OpenAI-compatible routes:
The Anthropic-compatible Messages routes never run the fallback chain, so this error comes only from the OpenAI-compatible routes. If the last provider answered with an error the agent doesn’t fail over on, you get that error as you would without fallbacks: a 400 comes back as the provider’s error, and a 401, 402 or 403 (while Rejects the key or model is off) as a 502 with code upstream_credentials_rejected. Responses to requests that ran through the fallback route, errors included, also carry X-Xenovia-Provider, X-Xenovia-Provider-Id, X-Xenovia-Model, X-Xenovia-Attempts and, when the request switched providers, X-Xenovia-Fallback-Reason. Log them with X-Xenovia-Trace-Id.

Limits

The runtime has no per-agent rate limit. Requests are metered against the organization’s request allowance; when it is exhausted the runtime returns 402. Upstream provider rate limits pass through as a 429 with the provider’s Retry-After, unless a fallback provider takes the request.

Retry guidance

Log X-Xenovia-Trace-Id for every non-2xx response.