error-handling

These patterns apply to all API endpoint handlers in this codebase. Every error must be handled explicitly — no unhandled exceptions may reach the HTTP framework.

Fundamental rule

All errors are caught and formatted at the handler level (or in a central error-handling middleware/decorator that wraps every handler). The framework never renders an unhandled exception as a response.

Central error handling

Use the shared error-handling decorator or middleware for every handler. Do not write try/catch blocks that format HTTP responses directly inside business logic. The pattern:

request → auth middleware → handler → error middleware → formatted response

If the handler throws, the error middleware intercepts it, logs it if appropriate, and converts it to the standard error envelope before sending the response.

Logging rules

Log 5xx errors (unexpected server errors) at the ERROR level with:

• Request ID (from the X-Request-ID header, or generate one if absent)
• Error message
• Full stack trace
• Request method and path (not the full URL — avoid logging query parameters that may contain tokens)

Do not log 4xx errors at ERROR level. Log them at DEBUG level if useful for debugging, but 4xx errors are expected client behavior and should not generate noise in error monitoring.

Never log request bodies or response bodies unless explicitly enabled for debugging in a non-production environment.

What belongs in API responses

Never include in an API error response:

• Stack traces
• SQL queries or database error messages
• Internal file paths
• Environment variable names or values
• Dependency version strings

Always include:

• A stable code in SCREAMING_SNAKE_CASE
• A human-readable message safe for end users

Mapping error types to status codes

Input validation errors → 422

Use 422 when the request is syntactically valid but semantically invalid (missing required fields, wrong value format, business rule violation detectable before touching external state).