> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xenovia.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Every status the runtime returns, in the error format of the API you called, and when to retry.

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](https://docs.xenovia.io/reference/errors.md).

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`:

```json theme={null}
{
  "error": {
    "message": "invalid api key for this agent",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}
```

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:

```json theme={null}
{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "invalid api key for this agent"
  },
  "request_id": "7c9e2a4e-6b1f-4f5e-9a3c-2d8f0b1a4c55"
}
```

The Anthropic SDKs raise these as their usual typed errors (`AuthenticationError`, `RateLimitError`, `OverloadedError`, and so on).

## Runtime status codes

| Status | Meaning | OpenAI `type` and `code` | Anthropic `error.type` |
| - | - | - | - |
| `400` | Invalid or empty JSON body, a missing field, an unsupported modality or content part, a malformed `X-Xenovia-Session-Id`, or an `X-Xenovia-Agent-Role` header, which is no longer supported (use a [sub-agent](https://docs.xenovia.io/agents/sub-agents.md) key) | `invalid_request_error` | `invalid_request_error` |
| `401` | Missing key, or a key that cannot act as this agent: unknown or revoked, another agent's key, a key for a deleted agent or for an agent ID that doesn't exist, or a key made only for coding-agent hooks (`invalid api key for this agent`) | `invalid_request_error`, code `invalid_api_key` | `authentication_error` |
| `402` | The organization's request allowance is exhausted, or billing access is restricted | `insufficient_quota`, code `insufficient_quota` | `billing_error` |
| `403` | The key belongs to a draft agent (`agent is not active: activate it in the Xenovia dashboard before sending requests`), or the session belongs to another organization | `permission_error` | `permission_error` |
| `404` | A malformed agent ID (anything but 1 to 128 letters, digits, `-` and `_`), or an unsupported path. The body is always JSON | `invalid_request_error`, code `not_found` | `not_found_error` |
| `405` | Wrong method on a supported path. The `Allow` header lists `OPTIONS, POST` | `invalid_request_error` | `invalid_request_error` |
| `413` | The request body is over the size limit | `invalid_request_error` | `request_too_large` |
| `429` | The provider rate-limited the request. `Retry-After` passes through | The provider's own type and code | `rate_limit_error` |
| `500` | An unexpected failure inside the runtime | `server_error` | `api_error` |
| `502` | The provider rejected the credential configured for the agent, or the agent has no usable provider | `api_error`, code `upstream_credentials_rejected` when the provider rejected the credential | `api_error` |
| `503` | Every provider the agent's route tried failed, or the provider is overloaded. `Retry-After` is set | `server_is_overloaded` | `overloaded_error` |
| `503` | A dependency (key verification, the config service, Neon, the session store, or billing) is briefly unavailable. `Retry-After` is set | `service_unavailable` | `api_error` |
| `504` | The request took longer than the runtime allows | `timeout` | `timeout_error` |

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](https://docs.xenovia.io/sdk/quickstart.md).

## 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](https://docs.xenovia.io/observability/sessions.md#what-a-block-looks-like-to-your-app). Only the steps of a [simulation](https://docs.xenovia.io/simulation.md) run still get a `403` for a block.

## Fallback providers

For an agent with [fallback providers](https://docs.xenovia.io/providers/fallbacks.md), 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:

```json theme={null}
{
  "error": {
    "message": "Every provider in this agent's route failed.",
    "type": "server_is_overloaded",
    "param": null,
    "code": null
  }
}
```

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](https://docs.xenovia.io/providers/fallbacks.md) takes the request.

## Retry guidance

| Status | Retry? | Notes |
| - | - | - |
| `429` | Yes | Upstream provider limit; wait for `Retry-After`, then back off with jitter |
| `500`, `503`, `504` | Yes | Transient; wait for `Retry-After` when it is set, then back off with jitter |
| `502` | Only if it isn't `upstream_credentials_rejected` | `upstream_credentials_rejected` means the provider refused the agent's saved credential. Fix it on the agent |
| `503` with `server_is_overloaded` or `overloaded_error` | Not right away | The agent's route ran out of providers (every provider tried failed, and any others were skipped), or the provider is overloaded. A retry runs the whole route again. Back off longer, or check [provider health](https://docs.xenovia.io/providers/fallbacks.md#provider-health) first |
| `400`, `422` | No | Fix the request |
| `401` | No | Fix the credential |
| `402` | No | Billing; contact your administrator |
| `403` | No | Activate the agent, or send a session ID from your own organization; not transient |
| `404` | No | Fix the agent ID or path; not transient |

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.