Errors

airmux keeps the error envelope native to the caller surface.

{"error": {"type": "invalid_request_error", "code": "unknown_model", "message": ""}}

{"type": "error", "error": {"type": "unknown_model", "message": ""}}

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, 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.

Inference

Operations

Control plane endpoints

Gateway codes

Streaming errors

​Gateway codes

​Streaming errors

Gateway codes

Streaming errors