Exception Handling

Execution Workflow

1. Separate startup and configuration failures from request-time failures.
2. Decide whether the failure should be represented by raising HTTPException or by mapping another exception type through an exception handler.
3. Choose the narrowest layer that should own the handler: app, router, controller, or route handler.
4. Keep the outbound error contract stable: status code, payload shape, media type, and safe detail level.
5. Register app-level handlers for 404 Not Found and 405 Method Not Allowed when those responses must be customized.
6. Verify validation and server-failure paths separately so sensitive details do not leak unintentionally.

Core Rules

• Distinguish configuration/startup exceptions from request-handling exceptions.
• Use HTTPException or its subclasses when the handler should raise an HTTP-aware error directly.
• Use exception handlers to translate domain or library exceptions into transport-safe responses.
• Keep error payload schemas stable across handlers and layers.
• Keep documented error behavior aligned with litestar-openapi route metadata and security docs.
• Redact or replace validation and internal error details when exposing raw messages would leak implementation details.