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

# Error Reference

> Stable Corvex Token Factory error codes, causes, remediation, and retry guidance.

The error envelope and `code` values below are stable for the Token Factory
API. New codes may be added without changing existing code meanings.

## Quick reference

| HTTP | Code | Category | Retryable? |
| - | - | - | - |
| 400 | `bad_request` | Request | No |
| 400 | `context_length_exceeded` | Request | No; compact or shrink the input, then retry |
| 401 | `invalid_api_key` | Authentication | No |
| 402 | `insufficient_credits` | Billing | No; resolve the billing or quota condition first |
| 403 | `virtual_key_blocked` | Authentication | No |
| 403 | `model_blocked` | Authentication | No |
| 404 | `model_unavailable` | Catalog | No |
| 404 | `not_found` | Request | No |
| 429 | `rate_limited` | Throttling | Yes; honor `Retry-After` |
| 429 | `token_limited` | Throttling | Yes; honor `Retry-After` |
| 500 | `server_error` | Server | Yes; use exponential backoff |
| 502 | `service_unavailable` | Capacity | Yes; use exponential backoff |
| 502 | `server_error` | Server | Yes; use exponential backoff |
| 503 | `model_unavailable` | Catalog | Yes; the model is temporarily not serving |
| 503 | `service_unavailable` | Capacity | Yes; use exponential backoff |

An HTTP `502` uses `service_unavailable` when the gateway cannot reach the model
backend and `server_error` when the backend returns `502`. Both are retryable.

## Categories

| Category | Meaning |
| - | - |
| **Authentication** | The key is missing, invalid, disabled, or not allowed for the requested scope. |
| **Billing** | A paid balance, quota, or configured spend cap is exhausted. |
| **Capacity** | The requested service or model is temporarily unavailable. |
| **Catalog** | The requested model is unknown or not currently serving. |
| **Request** | The request path or body is invalid. |
| **Server** | An unexpected platform or model-backend failure occurred. |
| **Throttling** | A request or token-rate limit was exceeded. |

## Error envelopes

The endpoint family decides the envelope shape (no content negotiation):
the OpenAI-compatible endpoints return the OpenAI-style envelope below,
and the Anthropic-compatible endpoints return the
[Anthropic-style envelope](#anthropic-endpoints-/v1/messages). The stable
`code` catalog is shared by both.

### OpenAI endpoints

All Token Factory OpenAI-family inference endpoints (`/v1/chat/completions`,
`/v1/completions`, `/v1/embeddings`, `/v1/models`, `/v1/responses`) return errors as
`Content-Type: application/json` with this shape:

```json theme={null}
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key",
    "type": "authentication_error"
  }
}
```

For `invalid_request_error`s where the failing field is identifiable, the
gateway additionally emits an optional `param`:

```json theme={null}
{
  "error": {
    "code": "bad_request",
    "message": "model field is required",
    "type": "invalid_request_error",
    "param": "model"
  }
}
```

* **`code`** — stable, snake\_case, machine-readable slug. **Match on this**
  in your client code. Codes do not change once published.
* **`message`** — human-readable string safe to surface in UIs or logs.
  The wording may change between releases — do not parse it.
* **`type`** — OpenAI-style category enum: `invalid_request_error`,
  `authentication_error`, `permission_error`, `not_found_error`,
  `rate_limit_error`, `server_error`, `service_unavailable`. Used by the
  OpenAI Python and TypeScript SDKs to pick the exception class
  (`AuthenticationError`, `RateLimitError`, etc.). Safe to ignore if you
  match on `code` directly.
* **`param`** *(optional)* — for `invalid_request_error`s, the request
  field at fault (`"model"`, `"input"`, `"messages"`, etc.). Omitted when
  no specific field is identifiable, and omitted on non-validation
  errors. Mirrors OpenAI's error-object shape so the OpenAI Python and
  TypeScript SDKs surface it on `BadRequestError.param`.
* **HTTP status** — conveys the broad category (auth, throttling, server,
  etc.). The `code` is the precise identity within that category.
* **`x-request-id`** *(response header)* — present on **every** response,
  including all errors (401/403/404 and every 4xx/5xx). Log it and quote it
  in support requests so a failure can be correlated end-to-end.

> [!NOTE]
>
> These endpoints return an OpenAI-compatible JSON envelope under
> `application/json`, not an RFC 7807 `application/problem+json` document.

### Anthropic endpoints (/v1/messages)

The Anthropic-compatible endpoints (`POST /v1/messages`,
`POST /v1/messages/count_tokens`) return every 4xx/5xx as
`Content-Type: application/json` with the Anthropic-style envelope,
extended with the same stable `code` catalog:

```json theme={null}
{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key",
    "code": "invalid_api_key"
  },
  "request_id": "req_abc123"
}
```

* **`error.type`** — Anthropic's published category enum:
  `invalid_request_error`, `authentication_error`, `permission_error`,
  `not_found_error`, `request_too_large`, `rate_limit_error`,
  `api_error`, `overloaded_error`. The Anthropic Python and TypeScript
  SDKs use it (with the HTTP status) to pick the exception class
  (`AuthenticationError`, `RateLimitError`, etc.). Relative to the
  OpenAI-style `type`, two values map: `server_error` → `api_error` and
  `service_unavailable` → `overloaded_error`; the rest are identical.
* **`error.code`** — the same stable, snake\_case catalog documented on
  this page. **Match on this** for precise handling — e.g.
  `rate_limited` vs `token_limited` both surface as `rate_limit_error`,
  and only `code` distinguishes them.
* **`error.message`** — human-readable; wording may change between
  releases. There is no `param` field on this surface — the failing
  request field is named in the message text instead.
* **`request_id`** — echoes your `X-Request-Id` request header (also
  returned as a response header) so you can correlate to gateway logs.
  Omitted when the request carried no `X-Request-Id`.
* **HTTP status** — unchanged from the table below; Token Factory does not adopt
  Anthropic's 529 (`overloaded_error` ships on 503) or 413 (oversized
  requests surface as 400 `bad_request`).

Errors raised by an upstream engine on these endpoints are normalized
into this same envelope before reaching you — clients never see a raw
engine error body (on either endpoint family). For example, an upstream
`502`/`504` surfaces as `api_error` and a `503` as `overloaded_error`:

```json theme={null}
{
  "type": "error",
  "error": {
    "type": "api_error",
    "message": "upstream service error",
    "code": "server_error"
  },
  "request_id": "req_abc123"
}
```

For `stream: true` requests, failures that occur before the stream starts
return this JSON envelope with the error status (not an SSE body).

## Codes

Each entry below documents:

* **Cause** — what triggered this error.
* **Remediation** — what the API consumer should do.
* **Retry** — whether the SDK retries this automatically, and how.
* **Where to look** — dashboards, settings, or support flow to investigate.

***

### invalid\_api\_key  (401)

**Cause.** No `Authorization: Bearer <key>` header, malformed header, or
the key value is unknown to the gateway.

**Remediation.** Create or rotate an API key (`sk-corvex-*`) in the
dashboard and send it as `Authorization: Bearer sk-corvex-...` (or as an
`x-api-key` header on the Anthropic `/v1/messages` surface). See
[Authentication](https://docs.corvex.cloud/getting-started/authentication.md) for the key
types.

**Retry.** No. This is a non-retryable client error.

**Where to look.** Dashboard → API Keys. Revoked keys appear with status
`disabled`; expired keys must be replaced.

```json theme={null}
{ "error": { "code": "invalid_api_key", "message": "Invalid API key", "type": "authentication_error" } }
```

***

### virtual\_key\_blocked  (403)

**Cause.** The API key has been deactivated.

**Remediation.** Create a new API key in the dashboard. If access remains
blocked, contact [Token Factory support](https://docs.corvex.cloud/reference/faq.md#how-do-i-contact-support).

**Retry.** No.

**Where to look.** Dashboard → API Keys → key status. Audit log will show
the deactivation event.

```json theme={null}
{ "error": { "code": "virtual_key_blocked", "message": "Virtual key is deactivated", "type": "permission_error" } }
```

***

### model\_blocked  (403)

**Cause.** The key is active, but the requested model is not among the
models allowed for your account or key.

**Remediation.** Use a model your account is allowed to call (list them
with `GET /v1/models`), or contact
[Token Factory support](https://docs.corvex.cloud/reference/faq.md#how-do-i-contact-support) about model access.

**Retry.** No.

**Where to look.** Dashboard → API Keys → key detail → Allowed models.

```json theme={null}
{ "error": { "code": "model_blocked", "message": "Model not allowed for this virtual key", "type": "permission_error" } }
```

***

### model\_unavailable  (404)

> [!NOTE]
>
> The HTTP status determines how to handle this code. A 404 means the model is
> not in the public catalog and is not retryable. A 503 means the model is in the
> catalog but temporarily not serving; retry that response with bounded
> exponential backoff.

**Cause.** The requested model identifier (e.g.
`some-org/Nonexistent-Model`) is not in the public catalog.

**Remediation.** List available models via `GET /v1/models` and pick a
model returned by the gateway.

**Retry.** No for this 404 response.

**Where to look.** The models list endpoint: `GET /v1/models`.

```json theme={null}
{ "error": { "code": "model_unavailable", "message": "Model not available", "type": "not_found_error" } }
```

***

### not\_found  (404)

**Cause.** The request reached a valid inference surface prefix (`/v1/…`
or `/openai/v1/…`) but no endpoint matched — e.g. `GET /v1/models/{id}`
or a typo like `GET /v1/bogus`. Distinct from `model_unavailable`, which
means the endpoint matched but the model is not serveable.

**Remediation.** Check the path against the [API
reference](https://docs.corvex.cloud/api-reference/openapi.md). Unknown `/v1/*` paths return
this structured envelope rather than a bare string, so SDK error
parsing stays intact.

**Retry.** No. This is a non-retryable client error.

**Where to look.** Your request URL. The `x-request-id` response header
correlates the 404 in the gateway logs.

```json theme={null}
{ "error": { "code": "not_found", "message": "unknown endpoint: /v1/bogus", "type": "not_found_error" } }
```

***

### rate\_limited  (429)

**Cause.** Your account's request-rate limit or an API key's concurrent-request
limit was reached, or the requested model is temporarily at capacity.

**Remediation.** Slow down. If the response includes a `Retry-After`
header (in seconds), wait that long before retrying. Otherwise back off
exponentially.

**Retry.** **Yes.** Honor `Retry-After` when present and otherwise use
exponential backoff. SDK defaults vary by package and version; configure the
attempt count explicitly for production clients.

**Where to look.** Check your [account limits](https://tokenfactory.corvex.cloud/app/settings/limits)
in the dashboard. To request higher limits, contact
[Token Factory support](https://docs.corvex.cloud/reference/faq.md#how-do-i-contact-support).

```json theme={null}
{ "error": { "code": "rate_limited", "message": "Request rate limit exceeded", "type": "rate_limit_error" } }
```

***

### token\_limited  (429)

**Cause.** A configured token-usage limit for your account was exceeded.
This limit is separate from the request-rate limit.

**Remediation.** Same as `rate_limited`. The response `code` is
`token_limited` (not `rate_limited`), so you can branch on which limit was
hit; the SDKs surface both as a `RateLimitError`.

**Retry.** **Yes**, same retry policy as `rate_limited`. Honor
`Retry-After`.

**Where to look.** Review token usage in the dashboard. For questions about
a configured token limit, contact
[Token Factory support](https://docs.corvex.cloud/reference/faq.md#how-do-i-contact-support).

```json theme={null}
{ "error": { "code": "token_limited", "message": "Token rate limit exceeded", "type": "rate_limit_error" } }
```

***

### insufficient\_credits  (402)

**Cause.** Your account's available credit balance has reached
zero, a hard quota has been exhausted, or a configured monthly
spend cap has been reached.

**Remediation.** For an exhausted credit balance, add credits through the
[dashboard](https://tokenfactory.corvex.cloud/app/billing).
For quota or spend-cap exhaustion, contact [Token Factory support](https://docs.corvex.cloud/reference/faq.md#how-do-i-contact-support) or wait
for the configured reset window.

**Retry.** No. Retrying before the billing or quota condition is resolved will
return the same error.

Match on `code` (`insufficient_credits`), not `type`: on the OpenAI surface
this carries `type: permission_error` (there is no billing-specific type).

**Where to look.** Check the dashboard's billing and usage sections, or contact
[Token Factory support](https://docs.corvex.cloud/reference/faq.md#how-do-i-contact-support).

```json theme={null}
{ "error": { "code": "insufficient_credits", "message": "Workspace has insufficient credits", "type": "permission_error" } }
```

***

### bad\_request  (400)

**Cause.** The request body is malformed, missing required fields, or
fails server-side validation. Examples: missing `model`, missing
`messages` for chat completions, or invalid JSON.

Common validation cases:

| Condition | Endpoint | `param` | Corrective action |
| - | - | - | - |
| A chat or embedding model is sent to the legacy text-completions API | `POST /v1/completions` | `model` | Use `/v1/chat/completions` or a model with text-completion support. |
| A model without embedding support is used | `POST /v1/embeddings` | `model` | Choose an embedding-capable model. No embedding model is currently deployed. |
| Image content is sent to a text-only model | Chat or Messages API | `messages` | Use a vision-capable model or remove the image block. |
| `max_tokens` is negative or not an integer | Chat Completions, legacy Completions, or Messages API | `max_tokens` | Send a non-negative integer or omit the optional field. |
| `max_output_tokens` is negative or not an integer | Responses API | `max_output_tokens` | Send a non-negative integer or omit the optional field. |

Integer-valued numbers such as `5.0` and `1e3`, and the value `0`, are accepted.

**Remediation.** Read the `message` for the specific field at fault and
correct the request. For the legacy-completions case, call
`/v1/chat/completions` (recommended), or switch the `model` to a
text-completion model. The [API reference](https://docs.corvex.cloud/api-reference/openapi.md) documents the
public request schemas.

**Retry.** No. Retrying the same payload will return the same error.

**Where to look.** Validate the request against the public OpenAPI schema and
call `GET /v1/models` to check model capabilities.

```json theme={null}
{ "error": { "code": "bad_request", "message": "Model is required", "type": "invalid_request_error" } }
```

```json theme={null}
{ "error": { "code": "bad_request", "message": "model 'zai-org/GLM-5.3' does not support /v1/completions; use /v1/chat/completions instead", "type": "invalid_request_error", "param": "model" } }
```

```json theme={null}
{ "error": { "code": "bad_request", "message": "model 'zai-org/GLM-5.3' does not support the /v1/embeddings endpoint", "type": "invalid_request_error", "param": "model" } }
```

```json theme={null}
{ "error": { "code": "bad_request", "message": "messages: required", "type": "invalid_request_error", "param": "messages" } }
```

```json theme={null}
{ "error": { "code": "bad_request", "message": "model 'zai-org/GLM-5.3' does not support image input", "type": "invalid_request_error", "param": "messages" } }
```

```json theme={null}
{ "error": { "code": "bad_request", "message": "max_tokens must be a non-negative integer", "type": "invalid_request_error", "param": "max_tokens" } }
```

```json theme={null}
{ "error": { "code": "bad_request", "message": "max_output_tokens must be a non-negative integer", "type": "invalid_request_error", "param": "max_output_tokens" } }
```

***

### context\_length\_exceeded  (400)

**Cause.** The request's input (or input + `max_tokens`) exceeds the model's
context window. The gateway surfaces this as a stable code whenever the
upstream engine reports a context-length rejection — on both endpoint
families, and including engine failures initially reported as a 5xx that the
gateway downgrades to the spec-correct 400. The `message` carries the
engine's own token accounting (e.g. the model's maximum context length and
your requested totals) where the engine reports it.

**Remediation.** Reduce the input: compact the conversation, drop or truncate
older turns or tool outputs, or lower `max_tokens`. For agentic clients
(Claude Code and similar harnesses), treat this code as the compact-and-retry
signal. To size a session up front, read the model's limits from
`GET /v1/models`: `context_window` (total), `max_output_tokens` (the model's
completion cap), and — only for a model whose output cap sits below its
window — `max_input_tokens` (`context_window − max_output_tokens`). That last
value is the input ceiling for a request that reserves the full output cap; a
request with a smaller `max_tokens` has correspondingly more input room, since
the engine enforces `input + max_tokens ≤ context_window`.

**Retry.** No. Retrying the same payload returns the same error. Retry only
after compacting or otherwise shrinking the input.

**Where to look.** The model's limits on `GET /v1/models` (`context_window`,
`max_output_tokens`, `max_input_tokens`), and the `message` field for the
engine's token accounting.

OpenAI envelope:

```json theme={null}
{ "error": { "code": "context_length_exceeded", "message": "prompt tokens + max_tokens exceeds the model's maximum context length of 262144", "type": "invalid_request_error" } }
```

Anthropic envelope:

```json theme={null}
{ "type": "error", "error": { "type": "invalid_request_error", "message": "prompt tokens + max_tokens exceeds the model's maximum context length of 262144", "code": "context_length_exceeded" }, "request_id": "req_abc123" }
```

***

### server\_error  (500, 502)

**Cause.** An unexpected server-side failure: a downstream component
crashed, a database call failed, or the gateway hit an internal panic.
On HTTP 502, this code means the upstream engine itself answered 502
and the gateway normalized its error body into the standard envelope.

**Remediation.** Retry with exponential backoff. If the error persists after
the configured retries, capture a sample response and its `x-request-id` header
before contacting support.

**Retry.** **Yes.** Use exponential backoff and a bounded retry count. SDK
defaults vary by package and version.

**Where to look.** Quote the `x-request-id` response header in a support
request so the failure can be correlated.

```json theme={null}
{ "error": { "code": "server_error", "message": "Internal server error", "type": "server_error" } }
```

***

### service\_unavailable  (502, 503)

**Cause.** The platform is temporarily over capacity, or the requested
model is still starting up and not yet ready to serve. On HTTP 502, the
gateway could not reach the model backend at all.

**Remediation.** Retry with exponential backoff. Honor `Retry-After` when
present.

**Retry.** **Yes**, same policy as `server_error`.

**Where to look.** Confirm that `GET /v1/models` lists the model. If it does not,
choose an available model; if it does, retry after the temporary failure.

```json theme={null}
{ "error": { "code": "service_unavailable", "message": "Service temporarily unavailable", "type": "service_unavailable" } }
```

***

## Retry semantics

The official OpenAI and Anthropic SDKs include automatic retry behavior, but the
exact statuses, delays, and attempt counts depend on the SDK and version.

For Token Factory responses:

* **Retry:** HTTP `429` (`rate_limited`, `token_limited`) and `5xx` responses,
  including a temporary `503 model_unavailable`.
* **Do not retry:** Other `4xx` responses, including `bad_request`,
  `context_length_exceeded`, `invalid_api_key`, `virtual_key_blocked`,
  `model_blocked`, the `404` form of `model_unavailable`, and
  `insufficient_credits`.
* **Backoff.** Use exponential backoff with a bounded maximum delay and attempt
  count. Configure these values for the latency and reliability needs of your
  application.
* **`Retry-After` header.** When the server returns `Retry-After`, the SDK
  waits at least that long before retrying. The header takes precedence
  over the default exponential backoff.

Both `rate_limited` and `token_limited` are surfaced by the SDKs as a
`RateLimitError` (a subclass of `APIError`). To tell which limit was hit,
match on the wire `error.code` (`rate_limited` vs `token_limited`) — the
OpenAI `error.type` is `rate_limit_error` for both. Use the `Retry-After`
response header to decide how long to wait.

## Prompt caching (`cache_control`)

The Anthropic Messages surface (`POST /v1/messages`,
`POST /v1/messages/count_tokens`) accepts `cache_control` annotations on system
and message content blocks. Token Factory does not interpret the annotation as a
request to cache content.

When the model backend reports cache usage, Token Factory passes those values
through. When the backend omits them, the response includes explicit zero values
in the non-streaming `usage` object or streaming `message_start` event:

```json theme={null}
"usage": {
  "input_tokens": 32,
  "output_tokens": 10,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 0
}
```

A zero value preserves the Anthropic-compatible usage shape and does not
indicate an error.

`cache_read_input_tokens` counts the input tokens that the engine served from
its prefix cache; `input_tokens` does not include them. Cached input tokens are
billed at the model's cached input rate, and no cache write is charged. See
[Pricing: Cached input tokens](https://docs.corvex.cloud/pricing.md#cached-input-tokens).

## Related documentation

* [DeepSeek Harness](https://docs.corvex.cloud/integrations/deepseek-harness.md) — setup and troubleshooting.
* [API Reference](https://docs.corvex.cloud/api-reference/openapi.md) — endpoint-by-endpoint
  request/response schemas, including error responses per endpoint.
* [Authentication](https://docs.corvex.cloud/getting-started/authentication.md) — virtual
  keys (`sk-corvex-*`) for inference.
* [Quickstart](https://docs.corvex.cloud/getting-started/quickstart.md) — first inference
  call end-to-end.


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