Reason codes & error model

Every denial and admin error carries a stable machine reason and a safe, structured shape. This is what lets you build automation and diagnostics on top of the gateway without scraping prose.

The error envelope

Admin API errors return a consistent envelope (gateway.admin-error/v1) with fields such as:

• reasonCode — the stable machine reason (e.g. invalid_auth_context).
• retryable — whether retrying could succeed.
• machineSafe — a safe, human‑readable summary.
• redactionStatus — confirmation that no sensitive material is included.

Denials from policy evaluation carry the matched (or missing) rule and the policy version — never the request payload. Turn a reason code into a full diagnosis with Diagnose a denial.

Common reason-code families

Family	Examples
Auth	invalid_auth_context, token_expired, jwks_unavailable
Policy	no_matching_allow, explicit_deny, surface_not_permitted
Credential	credential_unavailable, credential_mode_not_allowed
Connectivity	connector_unavailable, host_not_allowlisted
Session	session_revoked, session_not_found

Catalog source

The live catalog is available at GET /v1/reason-codes (filterable by resource type and action). In some deployment modes that endpoint can return an empty set; in that case treat the documented families above as the canonical reference, and the live endpoint as a supplement once populated.