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

# Errors

> Handle stable gateway error codes, provider errors, and failures that arrive after streaming begins.

`airmux` keeps the error envelope native to the caller surface.

<CodeGroup>
  ```json Chat Completions or Responses theme={null}
  {"error": {"type": "invalid_request_error", "code": "unknown_model", "message": ""}}
  ```

  ```json Messages theme={null}
  {"type": "error", "error": {"type": "unknown_model", "message": ""}}
  ```
</CodeGroup>

Authentication, parsing, policy, provider, and buffered execution failures use the protocol bound to the request path.
Model discovery uses the OpenAI error shape.

## Gateway codes

| HTTP | Code                             | Meaning                                                                                               |
| ---- | -------------------------------- | ----------------------------------------------------------------------------------------------------- |
| 400  | `invalid_request`                | Malformed JSON or a value failed schema validation                                                    |
| 400  | `unsupported_feature`            | Surface, model, or provider cannot represent a requested feature                                      |
| 400  | `unsupported_input_modality`     | Model does not support an input image or PDF                                                          |
| 401  | `missing_bearer_token`           | No non-empty bearer token, API-key header, or playground cookie                                       |
| 401  | `invalid_token`                  | The selected inference key is unknown, expired, revoked, or not adopted yet                           |
| 402  | `credential_unavailable`         | Policy and scope selection left no eligible credential                                                |
| 403  | `policy_denied`                  | A matching workspace restriction rejected the request                                                 |
| 403  | `missing_requested_with`         | Playground-cookie authentication lacks `X-Requested-With`                                             |
| 403  | `cross_site_request`             | Playground-cookie authentication supplied a `Sec-Fetch-Site` value other than `same-origin` or `none` |
| 404  | `unknown_model`                  | Catalog model ID does not exist in the active bundle                                                  |
| 502  | `provider_not_configured`        | Model references a provider absent from the bundle                                                    |
| 502  | `credential_missing`             | Eligible credential references could not resolve a value                                              |
| 502  | `invalid_upstream_response`      | Provider response or stream violated its expected protocol                                            |
| 502  | `upstream_unreachable`           | Provider connection failed                                                                            |
| 503  | `bundle_unavailable`             | Gateway has no accepted bundle                                                                        |
| 503  | `credential_backend_unavailable` | Secret store could not answer                                                                         |
| 504  | `upstream_timeout`               | Provider transport timed out                                                                          |
| 504  | `fallback_deadline_exceeded`     | Overall configured fallback deadline expired                                                          |

Provider HTTP errors may retain the provider status and normalized provider code. Do not branch only on the human
message; prefer HTTP status and `code` or `type`.

Every data-plane `401` response includes `WWW-Authenticate: Bearer realm="airmux"`. All data-plane HTTP responses carry the shared
[response headers](/docs/reference/inference#response-headers), including a gateway request ID.

Unexpected server failures may return a plain-text `500` body; the shared response headers still apply.

## Streaming errors

After response headers are sent, the HTTP status remains `200`. The stream emits a dialect-shaped error event and then
terminates. Treat either an error event or an incomplete terminal sequence as failure.

Retries belong in the workspace fallback policy or application layer. Avoid retrying validation errors, authentication failures, and policy denials.