Errors and streaming

Error format

{
  "error": {
    "message": "API key rate limit exceeded.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

HTTP	Common codes	Action
400	`unsupported_param`, `blocked_param`, `missing_parameter`, `unsupported_capability`, `invalid_multipart`, `unsupported_audio_format`, `unsupported_voice`, `input_required`, `voice_required`, `speech_input_too_long`, `invalid_speed`, `budget_output_limit_required`, `tenant_required`, `invalid_key_rotation`	Correct request/model, audio input, upload, or key-lifecycle configuration
401	`missing_api_key`, `invalid_api_key`, `admin_authentication_required`, `invalid_admin_credentials`, `oidc_login_failed`, `invalid_platform_handoff`	Check application/admin bearer token, console login, or restart the OIDC/Platform handoff flow
403	`endpoint_not_allowed`, `api_key_blocked`, `api_key_expired`, `admin_permission_required`, `invalid_admin_scope`, `tenant_scope_violation`	Check key scope/status or administrator role/tenant scope
409	`api_key_not_active`, `distributed_rate_limits_required`	Correct key lifecycle or configure Redis before creating a limited key
404	`model_not_found`	Discover allowed aliases
413	`request_body_too_large`, `audio_file_too_large`	Reduce payload or coordinate deployment/model limits
429	`rate_limit_exceeded`, `audio_concurrency_exceeded`, `budget_exceeded`, `admin_login_rate_limited`, `oidc_login_rate_limited`	Honor `Retry-After` when present; do not retry denial repeatedly
502	`provider_error`, `provider_connection_error`	Retry with capped exponential backoff if safe
503	`rate_limit_backend_unavailable`, `distributed_rate_limits_required`, `admin_login_throttle_unavailable`, `oidc_login_throttle_unavailable`, `admin_audit_unavailable`, `oidc_provider_unavailable`, or required dependency failure	Treat as temporary; shared enforcement and admin audit preflight fail closed. `distributed_rate_limits_required` needs a deployment configuration correction before retrying.
504	`provider_timeout`	Retry only when your operation is safe to repeat

Provider client errors can include sanitized actionable detail. Provider server errors remain generic and credentials are redacted.

Streaming

Chat and Responses support Server-Sent Events. Normalized streams finish with data: [DONE]. The gateway closes the provider stream and completes usage, budget, and request-log finalization before sending that terminal frame. Responses streams preserve event names such as response.created and response.completed. A provider failure after streaming begins is sent as a separately framed SSE error because the HTTP status has already been committed, including when the provider disconnected during an unterminated event. Raw UTF-8 characters may span transport chunks and are decoded incrementally. Applications must handle error objects inside the stream as well as connection failures. Client disconnects close the upstream stream and trigger cancellation-shielded usage/budget finalization. Usage fields accumulate across provider events; an empty trailing usage object does not discard previously observed counts. Terminal usage still depends on provider support, and budget settlement is conservative when usage is missing.

Request correlation

Send X-Request-ID using 1-128 letters, digits, ., _, :, or -, beginning with an alphanumeric character. Invalid values are replaced with a generated UUID. Log the response X-Request-ID for support and reconciliation.

Overview

Get Started

Administration

API Reference

Operations

Error format

Streaming

Request correlation

​Error format

​Streaming

​Request correlation

Error format

Streaming

Request correlation