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

# Errors and streaming

> Error response shape, status codes, and Server-Sent Events streaming behavior.

## Error format

```json theme={null}
{
  "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.