Errors - Auriko

Auriko returns errors in the format matching the endpoint’s API family. OpenAI-compatible endpoints (/v1/chat/completions, /v1/models, etc.) use the OpenAI error envelope. Anthropic-compatible endpoints (/v1/messages, /v1/messages/count_tokens) use the Anthropic error envelope.

Error envelope

OpenAI error envelope

Every non-2xx response on OpenAI-compatible endpoints uses this shape:

{
  "error": {
    "message": "Model 'gpt-5-turbo' is not in the catalog. See the models endpoint for the current list.",
    "type": "not_found_error",
    "code": "model_not_found",
    "param": "model",
    "doc_url": "https://docs.auriko.ai/errors/model_not_found"
  }
}

Field	Type	Required	Purpose
`message`	string	yes	Human-readable, actionable. Don’t branch on text.
`type`	string	yes	One of six categories (see below). Drives SDK class.
`code`	string \| null	yes	Stable machine identifier. Branch on this.
`param`	string \| null	yes	Offending field name. `null` when not attributable.
`doc_url`	string	recommended	Link to the error’s docs page.
`provider`	string \| null	no	Upstream provider that generated the error. Null for non-provider errors.
`suggestion`	string	no	Actionable fix hint for routing/capability errors. Absent for other error types.

Notes:

The envelope is flat under error. There is no details[] array and no nested error objects.
Content-Type is application/json; charset=utf-8 on every error response.
The response body is never empty; even 401 and 404 carry the envelope.

Anthropic error envelope

Anthropic-compatible endpoints (/v1/messages and /v1/messages/count_tokens) return errors in the Anthropic Messages API format:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Request body must be a JSON object."
  }
}

Field	Type	Required	Purpose
`type` (top-level)	string	yes	Always `"error"`.
`error.type`	string	yes	One of nine categories (see table below).
`error.message`	string	yes	Human-readable description. Don’t branch on text.
`error.suggestion`	string	no	Actionable fix hint for routing/capability errors. Absent for other error types.

The Anthropic envelope doesn’t carry code, param, or doc_url. Routing failures include an optional suggestion with an actionable fix hint. Branch on error.type and HTTP status instead.

`error.type`	When
`invalid_request_error`	400 — malformed or invalid request
`authentication_error`	401 — missing or invalid API key
`permission_error`	403 — authenticated but not allowed
`not_found_error`	404 — resource doesn’t exist
`request_too_large`	413 — payload exceeds size limit
`rate_limit_error`	429 — rate or quota limit hit
`billing_error`	402 — billing issue
`api_error`	500 / 502 / 503 / 504 — server-side fault
`overloaded_error`	529 — temporarily overloaded

Required headers

Every response — success and error — carries:

x-request-id — unique per request. Copy this when opening a support ticket. SDKs expose it as request_id (Python) / requestId (TypeScript) on every raised exception.

Error responses also carry, when applicable:

Retry-After — integer seconds. Present on 429 and 503. SDKs read this for automatic backoff.

Error types (OpenAI envelope)

The OpenAI envelope’s type field uses a closed set of six values:

`type`	When	SDK class
`invalid_request_error`	400 / 405 / 409 / 413 / 422 — malformed or semantically invalid request	`BadRequestError` (or `ConflictError` on 409)
`authentication_error`	401 — missing, malformed, or invalid API key	`AuthenticationError`
`permission_error`	403 — authenticated but not allowed	`PermissionDeniedError`
`not_found_error`	404 — resource doesn’t exist or isn’t visible	`NotFoundError`
`rate_limit_error`	429 — rate or quota limit hit	`RateLimitError`
`api_error`	5xx — server-side fault or upstream failure	`InternalServerError` (500) / `APIStatusError` (502 / 503 / 504)

Error codes

These 52 codes are the canonical set. Codes are stable — once published, meaning never changes.

Authentication and authorization

Code	HTTP	`type`
`invalid_api_key`	401	`authentication_error`
`expired_api_key`	401	`authentication_error`
`insufficient_permissions`	403	`permission_error`
`feature_disabled`	403	`permission_error`
`mfa_required`	403	`permission_error`
`invalid_recovery_code`	401	`authentication_error`
`mfa_verification_failed`	401	`authentication_error`

Request validation

Code	HTTP	`type`
`invalid_request`	400	`invalid_request_error`
`missing_required_parameter`	400	`invalid_request_error`
`invalid_parameter_value`	400	`invalid_request_error`
`payload_too_large`	413	`invalid_request_error`
`context_length_exceeded`	400	`invalid_request_error`
`content_filtered`	400	`invalid_request_error`
`idempotency_conflict`	409	`invalid_request_error`
`field_immutable`	400	`invalid_request_error`
`operation_not_allowed`	400	`invalid_request_error`
`unknown_field`	400	`invalid_request_error`
`method_not_allowed`	405	`invalid_request_error`
`duplicate_resource`	409	`invalid_request_error`
`state_precondition_failed`	409	`invalid_request_error`

Routing — capability

Code	HTTP	`type`
`tools_not_supported`	400	`invalid_request_error`
`json_mode_not_supported`	400	`invalid_request_error`
`structured_output_not_supported`	400	`invalid_request_error`
`tools_with_structured_output_not_supported`	400	`invalid_request_error`
`vision_not_supported`	400	`invalid_request_error`
`reasoning_not_supported`	400	`invalid_request_error`
`thinking_disable_not_supported`	400	`invalid_request_error`
`streaming_not_supported`	400	`invalid_request_error`
`non_streaming_not_supported`	400	`invalid_request_error`
`batch_only`	400	`invalid_request_error`
`tier_opt_in_required`	400	`invalid_request_error`
`tool_choice_required_not_supported`	400	`invalid_request_error`

Routing — constraint

Code	HTTP	`type`
`cost_constraint_exceeded`	400	`invalid_request_error`
`latency_constraint_exceeded`	400	`invalid_request_error`
`throughput_constraint_not_met`	400	`invalid_request_error`
`provider_not_in_allowlist`	400	`invalid_request_error`
`provider_blocked`	400	`invalid_request_error`
`required_params_not_supported`	400	`invalid_request_error`

Routing — policy

Code	HTTP	`type`
`byok_keys_required`	400	`invalid_request_error`
`platform_keys_unavailable`	400	`invalid_request_error`

Routing — modality

Code	HTTP	`type`
`unsupported_modalities`	400	`invalid_request_error`

Resources

Code	HTTP	`type`
`model_not_found`	404	`not_found_error`
`resource_not_found`	404	`not_found_error`

Rate limits and quotas

Code	HTTP	`type`
`rate_limit_exceeded`	429	`rate_limit_error`
`budget_exhausted`	429	`rate_limit_error`
`insufficient_quota`	429	`rate_limit_error`

Routing and providers

Code	HTTP	`type`
`no_provider_available`	503	`api_error`
`upstream_error`	502	`api_error`
`upstream_timeout`	504	`api_error`
`model_unavailable`	503	`api_error`

Server

Code	HTTP	`type`
`internal_error`	500	`api_error`
`service_unavailable`	503	`api_error`

Auriko abstracts over multiple upstream LLM providers. Error messages name the model and the upstream provider that produced the error. The provider name appears in error.provider and may appear in error.message. Failover across providers happens automatically before a 429 or 5xx surfaces to the client.

Retry policy

Branch on type and code, not on HTTP status alone. The SDK retry loop uses the same rules.

Condition	Retryable	Notes
`type: rate_limit_error` + `code: rate_limit_exceeded`	yes	Honor `Retry-After` header.
`type: rate_limit_error` + `code: budget_exhausted`	no	Top up credits or raise the budget.
`type: rate_limit_error` + `code: insufficient_quota`	no	Account has no quota on the current plan.
`type: api_error` + status 500 / 502 / 503 / 504 (except `code: internal_error`)	yes	Exponential backoff. Honor `Retry-After` on 503.
`type: api_error` + `code: internal_error`	no	Unclassified fault; retrying won’t help. Contact support with `x-request-id`.
`type: authentication_error` / `permission_error` / `not_found_error` / `invalid_request_error`	no	Client-side fix required.
Network failure before any response (DNS, TCP, TLS)	yes	SDK raises `APIConnectionError`.

Anthropic-compatible endpoints don’t carry code. The Anthropic SDK retries based on HTTP status.

Mid-stream errors (SSE)

Streaming endpoints return Content-Type: text/event-stream. When the HTTP status is already committed as 200 OK and an error occurs mid-stream, the envelope surfaces as a final data: event and the stream closes:

HTTP/1.1 200 OK
Content-Type: text/event-stream
x-request-id: req_01HXABCDEFGHJKMNPQRSTVWXYZ

data: {"id":"chatcmpl_01HX...","choices":[{"delta":{"content":"Hello"},"index":0}]}

data: {"error":{"message":"Upstream timed out after 30 seconds.","type":"api_error","code":"upstream_timeout","param":null,"provider":"openai","doc_url":"https://docs.auriko.ai/errors/upstream_timeout"}}

Rules:

Errors never emit as partial JSON or a different SSE event name.
data: [DONE] signals successful completion only. After an error event, no [DONE] follows.
The connection closes immediately after the error event.

SDK exception dispatch

The Python and TypeScript SDKs dispatch incoming envelopes to typed exceptions. Every instance exposes message, type, code, param, request_id, doc_url, status_code, retry_after_seconds, and provider.

import os
from auriko import Client
from auriko.errors import (
    AurikoAPIError,
    APIConnectionError,
    AuthenticationError,
    PermissionDeniedError,
    BadRequestError,
    ConflictError,
    NotFoundError,
    RateLimitError,
    InternalServerError,
    APIStatusError,
)

client = Client(api_key=os.environ["AURIKO_API_KEY"])

try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello!"}],
    )
except AuthenticationError as e:
    print(f"Check your API key. request_id={e.request_id}")
except PermissionDeniedError as e:
    print(f"Not allowed: {e.message} (code={e.code})")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after_seconds}s")
except NotFoundError as e:
    print(f"Not found: {e.message} (param={e.param})")
except BadRequestError as e:
    print(f"Bad request: {e.message} (param={e.param})")
except ConflictError as e:
    print(f"Conflict: {e.message} (code={e.code})")
except InternalServerError as e:
    print(f"Server error. request_id={e.request_id}")
except APIStatusError as e:
    print(f"Upstream error ({e.status_code}): {e.message}")
except APIConnectionError as e:
    print(f"Network error: {e.message}")
except AurikoAPIError as e:
    print(f"API error ({e.status_code}): {e.message}")

Built-in retry

The SDK retries on APIConnectionError, rate_limit_error (except budget_exhausted and insufficient_quota), and api_error (except code: internal_error). Retries use exponential backoff and honor Retry-After when present.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AURIKO_API_KEY"],
    base_url="https://api.auriko.ai/v1",
    max_retries=2,
)

# Disable retries
client = OpenAI(
    api_key=os.environ["AURIKO_API_KEY"],
    base_url="https://api.auriko.ai/v1",
    max_retries=0,
)

Support

When reporting a failure to support, include the x-request-id from the response header (or request_id / requestId on the SDK exception). That single identifier pairs the client view with the server log.

Documentation Index

​Error envelope

​OpenAI error envelope

​Anthropic error envelope

​Required headers

​Error types (OpenAI envelope)

​Error codes

​Authentication and authorization

​Request validation

​Routing — capability

​Routing — constraint

​Routing — policy

​Routing — modality

​Resources

​Rate limits and quotas

​Routing and providers

​Server

​Retry policy

​Mid-stream errors (SSE)

​SDK exception dispatch

​Built-in retry

​Support

Error envelope

OpenAI error envelope

Anthropic error envelope

Required headers

Error types (OpenAI envelope)

Error codes

Authentication and authorization

Request validation

Routing — capability

Routing — constraint

Routing — policy

Routing — modality

Resources

Rate limits and quotas

Routing and providers

Server

Retry policy

Mid-stream errors (SSE)

SDK exception dispatch

Built-in retry

Support