/litestar-exceptions

name: litestar-exceptions
description: "Auto-activate for exception_handlers, HTTPException, ApplicationError, NotFoundException, ValidationException, PermissionDeniedException, RFC 9457, or domain error mapping. Not for client-side errors."

Litestar Exceptions

Use this skill for domain exception hierarchies, handler registration, and HTTP error response shape.

Code Style Rules

• Centralize domain-to-HTTP translation in exception handlers.
• Keep route handlers free of repetitive try/except blocks.
• Use domain exception classes when services need stable error contracts.
• Keep validation errors aligned with DTO and OpenAPI behavior.
• Use `ProblemDetailsPlugin` explicitly when the API contract requires RFC

9457. Native `HTTPException` responses are Litestar's JSON error envelope.

Quick Reference

• Exception patterns: [exceptions.md](references/exceptions.md)
• Pair with [litestar-auth-guards](../litestar-auth-guards/SKILL.md) for permission failures.
• Pair with [litestar-data-services](../litestar-data-services/SKILL.md) for not-found and conflict behavior.

<workflow>

Workflow

1. Define a small domain exception hierarchy. 2. Register handlers at app config. 3. Raise domain exceptions from services or Litestar exceptions from framework boundaries. 4. Test response status and payload shape.

</workflow>

<guardrails>

Guardrails

• Do not catch exceptions in every handler.
• Do not leak database exception messages to API clients.
• Do not return inconsistent error payloads from neighboring routes.
• Do not replace Litestar validation behavior without a clear API reason.
• Do not describe native `HTTPException` responses as Problem Details unless

`ProblemDetailsPlugin` is configured for them.

</guardrails>

<validation>

Validation Checkpoint

• [ ] Exceptions have stable status mapping.
• [ ] App-level handlers are registered.
• [ ] Services do not return sentinel error values.
• [ ] Tests cover representative failure responses.

</validation>

<example>

Example

class ApplicationError(HTTPException):
    status_code = 500


class ConflictError(ApplicationError):
    status_code = 409

</example>

References Index

• [exceptions.md](references/exceptions.md)

Official References

• <https://docs.litestar.dev/> - Litestar documentation
• <https://docs.litestar.dev/latest/reference/> - Litestar API reference
• <https://github.com/litestar-org/litestar/tree/v2.24.0> - Audited Litestar 2.24.0 source

Shared Styleguide Baseline

• [General](../litestar-styleguide/references/general.md)
• [Python](../litestar-styleguide/references/python.md)
• [Litestar](../litestar-styleguide/references/litestar.md)