Error guide

The error contract (SRS §9): every failure returns a stable code, message, correlation id, retryability and a recommended action.

What you will never receive

Provider credentials, internal secrets, sensitive policy expressions and internal stack traces are never exposed in error responses (DEV-010).

Error codes

All 16 codes with meaning, action and retryability.

Code	HTTP	Retryable	Meaning	Recommended action
AUTHENTICATION_FAILED	401	no	The credential is missing, malformed, revoked or unknown.	Provide a valid active credential.
AUTHORIZATION_DENIED	403	no	Your identity lacks the permission required for this operation.	Request the required permission from your administrator.
CREDENTIAL_SUSPENDED	401	no	The credential was suspended (manually or by policy).	Ask your administrator to reactivate the credential.
CREDENTIAL_EXPIRED	401	no	The credential passed its expiry time.	Rotate the credential and retry.
POLICY_DENIED	403	no	A routing/usage policy rejected the request before execution.	Adjust the request to satisfy policy, or request an exception.
DATA_POLICY_DENIED	403	no	The request contains data the data-protection policy blocks for this scope.	Remove restricted data from the request.
BUDGET_EXCEEDED	429	no	A hard budget limit was reached for the effective scope.	Raise the budget or reduce usage.
RATE_LIMITED	429	yes	A rate/token/concurrency limit was exceeded.	Retry with backoff.
INVALID_REQUEST	400	no	The request body or parameters failed validation.	Fix the request body.
UNSUPPORTED_CAPABILITY	400	no	The requested capability (vision, tools, streaming…) is not supported by eligible routes.	Use a supported capability for this route.
NO_ELIGIBLE_ROUTE	404	no	No model in your scope satisfies the request after policy and eligibility filtering.	Check model availability and entitlements.
ROUTING_UNAVAILABLE	503	yes	The routing engine is temporarily unavailable.	Retry shortly.
UPSTREAM_UNAVAILABLE	502	yes	The selected provider/model could not be reached.	Retry or pick another route.
UPSTREAM_TIMEOUT	504	yes	The provider did not respond within the timeout.	Retry with a shorter request.
STREAM_INTERRUPTED	502	yes	A streaming response was cut off mid-stream.	Reconnect the stream.
INTERNAL_ERROR	500	yes	Unexpected server-side failure.	Retry; contact support if it persists.

Error metadata fields

error.codeStable machine-readable code from the list above.

error.messageHuman-readable description (never a stack trace or internal secret).

error.correlation_idUnique request id — include it when contacting support.

error.retryableBoolean: whether an immediate retry can succeed.

error.recommended_actionThe next step the system suggests.

error.detailsOptional structured validation/policy details (safe subset only).

Alias semantics

A route alias is a stable name (e.g. chat.default) that maps to a versioned set of candidate models. You send the alias as model. The router picks a concrete model per request.

Versioning: alias targets are append-only versions. Changing candidates activates a new version — history is never overwritten, and rollback means re-activating a prior candidate set.

Fallback chain: if the selected candidate fails, the router walks the alias fallback chain before surfacing an error.

Compatibility: the alias name is the stable contract; the concrete model behind it may change as catalog states and policies evolve. Decisions record the alias, selected model and policy version for every request.