error-handling-security

Error-Handling Security

Rules (for AI agents)

ALWAYS

• Catch exceptions at the boundary — HTTP handler, RPC method, message consumer — and decide there what crosses to the client and what stays server-side. Record the failure with a correlation ID under logging-security's policy; do not bypass its redaction rules to attach "full context", which is how request bodies, cookies and tokens end up in logs.
• Put only client-actionable information in an external error: a stable error code, a short human-readable message, and the correlation ID. Anything the caller cannot act on belongs in the log entry that shares that ID.
• Keep responses consistent within an error class, and make security-equivalent outcomes externally indistinguishable. Different classes may and should differ — 400 VALIDATION_FAILED, 401, 403, 409, 429 are not a finding. What must not differ is a pair of outcomes whose distinction reveals protected state: whether an account exists, whether a record the caller may not see is present. auth-security owns making the login paths cost the same; this rule owns what they return.
• Disable developer error pages and detailed exception rendering in every non-development environment, and route unhandled errors through the framework's production error handler. This is a wiring decision, not the same thing as an environment variable reading production — the setting and its name differ per framework, and references/framework-error-pages.md has them.
• Render every external error through one helper, so the sanitization rules live in a single place instead of being re-derived at each handler.
• Consult api-security for the status code and response envelope, logging-security for the internal record, and auth-security for making two authentication failures cost the same. This skill owns one decision — what crosses the boundary.

NEVER

• Serialize exception or debug internals into an external response: stack traces, SQL fragments and constraint names, filesystem paths, internal hostnames, dependency or framework versions.
• Silently swallow an unexpected exception — a bare except: pass, catch {}, rescue nil. Let it reach the nearest designated error boundary, which logs it and converts it to a sanitized response. A narrowly-typed, commented suppression of an expected condition is fine; the finding is the broad or unexplained one.
• Withhold client-actionable validation detail in order to make the API harder to explore, or smuggle server state into it. Which field failed and why is the public contract — that is what RFC 9457 problem details and the GraphQL errors array are for — and it belongs in the response. Record existence, authorization state, and SQL or schema internals are not the contract and do not.