Error Reference

​

Error envelope

​

OpenAI endpoints

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key",
    "type": "authentication_error"
  }
}

{
  "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_errors, 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). Requests rejected at the gateway carry a minted req-gw-<hex> id; responses that reach an engine pass its id through. Log it and quote it in support requests so a failure can be correlated end-to-end (RD-919).

​

Anthropic endpoints (/v1/messages)

{
  "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; Corvex does not adopt Anthropic’s 529 (overloaded_error ships on 503) or 413 (oversized requests surface as 400 bad_request).

{
  "type": "error",
  "error": {
    "type": "api_error",
    "message": "upstream service error",
    "code": "server_error"
  },
  "request_id": "req_abc123"
}

​

Categories

​

Quick reference

​

Codes

• 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)

{ "error": { "code": "invalid_api_key", "message": "Invalid API key", "type": "authentication_error" } }

​

virtual_key_blocked (403)

{ "error": { "code": "virtual_key_blocked", "message": "Virtual key is deactivated", "type": "permission_error" } }

​

model_blocked (403)

{ "error": { "code": "model_blocked", "message": "Model not allowed for this virtual key", "type": "permission_error" } }

​

model_unavailable (404)

{ "error": { "code": "model_unavailable", "message": "Model not available", "type": "not_found_error" } }

​

not_found (404)

{ "error": { "code": "not_found", "message": "unknown endpoint: /v1/bogus", "type": "not_found_error" } }

​

rate_limited (429)

{ "error": { "code": "rate_limited", "message": "Request rate limit exceeded", "type": "rate_limit_error" } }

​

token_limited (429)

{ "error": { "code": "token_limited", "message": "Token rate limit exceeded", "type": "rate_limit_error" } }

​

insufficient_credits (402)

{ "error": { "code": "insufficient_credits", "message": "Workspace has insufficient credits", "type": "permission_error" } }

​

bad_request (400)

{ "error": { "code": "bad_request", "message": "Model is required", "type": "invalid_request_error" } }

{ "error": { "code": "bad_request", "message": "model 'Qwen/Qwen3-Embedding-0.6B' does not support /v1/completions; use /v1/chat/completions or /v1/embeddings instead", "type": "invalid_request_error", "param": "model" } }

{ "error": { "code": "bad_request", "message": "model 'Qwen/Qwen2.5-0.5B-Instruct' does not support /v1/completions; use /v1/chat/completions or /v1/embeddings instead", "type": "invalid_request_error", "param": "model" } }

{ "error": { "code": "bad_request", "message": "model 'MiniMaxAI/MiniMax-M2.5' does not support the /v1/embeddings endpoint", "type": "invalid_request_error", "param": "model" } }

{ "error": { "code": "bad_request", "message": "messages: required", "type": "invalid_request_error", "param": "messages" } }

{ "error": { "code": "bad_request", "message": "model 'MiniMaxAI/MiniMax-M2.5' does not support image input", "type": "invalid_request_error", "param": "messages" } }

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

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

​

server_error (500, 502)

{ "error": { "code": "server_error", "message": "Internal server error", "type": "server_error" } }

​

service_unavailable (502, 503)

{ "error": { "code": "service_unavailable", "message": "Service temporarily unavailable", "type": "service_unavailable" } }

​

Retry semantics

• Retry on: HTTP 429 (rate_limited, token_limited) and any HTTP 5xx (server_error, service_unavailable).
• Do not retry on: Other 4xx codes (bad_request, invalid_api_key, virtual_key_blocked, model_blocked, model_unavailable, insufficient_credits). These are raised immediately as APIError.
• Backoff. Starts at 1 s and doubles per attempt, up to a configurable maximum. Default is 3 retries.
• 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.

• retry_after — value (in seconds) from the last response’s Retry-After header, when present.
• type — the SDK’s RateLimitError.type property, either "token_limited" or "request_limited", so callers can distinguish which limit was hit. This is the SDK-side property and is distinct from the wire envelope’s error.type field (which is the OpenAI category enum "rate_limit_error").

​

Prompt caching (cache_control)

"usage": {
  "input_tokens": 32,
  "output_tokens": 10,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 0
}

​

See also

• API Reference — endpoint-by-endpoint request/response schemas, including error responses per endpoint.
• Authentication — virtual keys (sk-corvex-*) for inference, admin keys (sk-admin-*) for /api/* management.
• Quickstart — first inference call end-to-end.