Reason codes and errors

A status code identifies a broad failure class. A machine reason identifies the boundary that rejected the operation. Preserve the exact returned reason when investigating; do not infer a credential failure from every forbidden response.

Read the response in context

1. Record the HTTP or protocol error and its safe reason code.
2. Identify the request’s environment, caller, resource, and time.
3. Match the reason to the applicable API contract or schema.
4. Search the corresponding audit event and compare the active policy or projection.

Choose the next check

Boundary	Inspect
Authentication	Token verification and the configured identity flow.
Authorization	Principal, action, resource, context, and deny precedence.
Credentials	Binding state and allowed credential mode.
Route	Registered endpoint and compatibility profile.
Session	Missing, expired, revoked, or draining state.
Readiness	Dependencies and accepted configuration freshness.

Exact reason values come from the current contract and implementation. See troubleshooting for the diagnostic sequence. Never include token values or upstream secret material in an error report.