Authentication and Errors

Authenticate requests, inspect response headers, and handle stable gateway errors.

API key authentication

Create a key in Token Management and keep it in server-side secret storage. The same sk- platform key supports all public protocol dialects.

Header or query parameter	Recommended for
`Authorization: Bearer $API_KEY`	OpenAI-compatible and model-native APIs
`x-api-key: $API_KEY`	Anthropic SDKs
`x-goog-api-key: $API_KEY`	Gemini SDKs
`?key=$API_KEY`	Gemini clients that cannot set headers

Prefer headers. Query parameters can be retained in browser history, proxy logs, and analytics. Never expose a platform API key in public client-side code.

Authorization: Bearer sk-...
Content-Type: application/json

The gateway accepts protocol version headers such as anthropic-version, but the platform controls the version sent to upstream providers.

Response headers

Header	Meaning
`x-request-id`	Stable request ID for logs, billing investigation, and support. Present on business responses.
`x-dropped-params`	Fields omitted during cross-protocol conversion because no safe equivalent exists.
`Retry-After`	Suggested delay for rate or capacity responses when available.
`Access-Control-Expose-Headers`	Makes the request ID and configured aliases readable to browser clients.

All /v1/** paths support CORS. A successful preflight does not authenticate the later model request.

Request limits

Request kind	Default body limit
Chat and embeddings	32 MiB
Images	100 MiB
Video tasks	50 MiB

A deployment can configure different limits. A body rejected at the transport boundary returns 413 request_too_large and the active limit in the message.

Platform-managed fields

The following controls do not select public gateway behavior:

provider, routing, and route are always rejected when present with a non-null value.
Paid or priority service tiers are managed by the platform. Neutral values such as auto, default, or standard can be accepted and removed before forwarding; paid-tier selections are rejected.
Idempotency-Key is rejected on model-call POST requests. It must not be interpreted as duplicate-call protection.

Error envelopes

The HTTP status retains its normal meaning. The JSON shape follows the endpoint dialect.

{
  "error": {
    "message": "model not found: vendor/model",
    "type": "invalid_request_error",
    "param": null,
    "code": "model_not_found"
  }
}

HTTP statuses

Status	Meaning	Typical gateway codes
`400`	Invalid shape, unsupported field, stateful feature, or capability	`invalid_request`, `stateful_not_supported`, `capability_unsupported`
`401`	Missing, invalid, disabled, or expired API key	`invalid_api_key`, `api_key_disabled`, `api_key_expired`
`402`	Available balance is insufficient	`insufficient_balance`
`404`	Model, task, or endpoint does not exist	`model_not_found`, `task_not_found`
`413`	Request body exceeds the active limit	`request_too_large`
`429`	RPM, TPM, API-key, or concurrency limit	`rate_limited`, `tpm_request_too_large`, `concurrency_limited`
`502`–`504`	No usable channel, upstream failure, or timeout	`no_available_channel`, `all_channels_failed`, `upstream_error`, `upstream_timeout`
`503`	Gateway or wallet state is warming, or channels are at capacity	`service_warming`, `wallet_warming`, `channel_capacity_exhausted`

Other stable codes include api_key_limit_exceeded, wallet_disabled, content_policy, config_error, stream_broken, stream_idle_timeout, balance_truncated, task_expired, and internal_error.

Retry rules

Read-only GET requests can be retried with bounded exponential backoff. For 429 and capacity responses, honor Retry-After when present.

Do not automatically retry a model-creation POST after an ambiguous disconnect or timeout: the upstream may already have accepted billable work. Streaming clients should preserve received output and distinguish a normal terminal event from a broken or balance-truncated stream. For asynchronous delivery, follow the dedicated task and callback rules.