Exception Handling
Use this skill when defining API error contracts and mapping domain failures to HTTP responses.
Workflow
-
Define domain exceptions for expected failure classes.
-
Map exceptions to Litestar handlers globally or by scope.
-
Return consistent error payload shapes.
-
Log with enough context for debugging without leaking sensitive details.
Pattern
from litestar import Litestar, Request from litestar.response import Response
class DomainError(Exception): pass
def domain_error_handler(_: Request, __: DomainError) -> Response[dict[str, str]]: return Response({"error": "domain_error"}, status_code=400)
app = Litestar( route_handlers=[], exception_handlers={DomainError: domain_error_handler}, )
Error Handling Checklist
-
Distinguish client errors (4xx) from server errors (5xx).
-
Keep payload structure stable (code , message , optional details ).
-
Pair exception mapping with tests for each expected failure mode.
Litestar References