Domain exceptions¶
Services raise domain exceptions, and one handler turns them into HTTP responses. No route raises HTTPException. A service says ExecutionNotFoundError(execution_id) and never thinks about status codes, so the same code works from a route, a Kafka handler or a test.
Base classes¶
Everything inherits from DomainError in app/domain/exceptions.py, which stores the text in message. The base class decides the status:
| Base class | Status | Meaning |
|---|---|---|
NotFoundError |
404 | entity doesn't exist; takes entity and identifier |
ValidationError |
422 | business rule violated |
ThrottledError |
429 | limit exceeded |
ConflictError |
409 | duplicate or concurrent change |
UnauthorizedError |
401 | not authenticated |
ForbiddenError |
403 | authenticated but not allowed |
InvalidStateError |
400 | operation not valid in the current state |
AccountLockedError |
423 | too many failed logins |
InfrastructureError |
500 | database, Kafka or Kubernetes failure |
A plain DomainError also maps to 500.
Hierarchy¶
Each domain package defines its own subclasses in an exceptions.py and exports them from its __init__.py:
DomainError
├── NotFoundError
│ ├── ExecutionNotFoundError execution
│ ├── NotificationNotFoundError notification
│ ├── SavedScriptNotFoundError saved_script
│ ├── ReplaySessionNotFoundError replay
│ ├── EventNotFoundError events
│ └── UserNotFoundError user
├── ValidationError
│ ├── RuntimeNotSupportedError execution
│ └── NotificationValidationError notification
├── ThrottledError
│ └── NotificationThrottledError notification
├── ConflictError
├── UnauthorizedError
│ ├── AuthenticationRequiredError user
│ └── InvalidCredentialsError user
├── ForbiddenError
│ ├── ExecutionAccessDeniedError execution
│ ├── AdminAccessRequiredError user
│ ├── AccountDeactivatedError user
│ └── CSRFValidationError user
├── InvalidStateError
│ ├── ExecutionNotRetryableError execution
│ ├── ExecutionTerminalError execution
│ └── SelfDeletionError user
├── InfrastructureError
│ └── ReplayOperationError replay
└── AccountLockedError
The right column is the package under app/domain/, so EventNotFoundError lives in app/domain/events/exceptions.py. A few of these have a status worth knowing. RuntimeNotSupportedError (422) rejects a language version that isn't offered, on execute, retry and saved scripts. ExecutionNotRetryableError (400) refuses to retry a queued or running execution, and ExecutionTerminalError (400) refuses to cancel a finished one. SelfDeletionError (400) stops an admin from deleting their own account.
CSRFValidationError never reaches the global handler: CSRFMiddleware catches it and answers 403 itself.
Subclasses that carry context take it in the constructor and keep it as attributes, so logs and tests can read exc.execution_id or exc.limit without parsing the message:
class ExecutionAccessDeniedError(ForbiddenError):
"""Raised when a non-admin user accesses another user's execution."""
def __init__(self, execution_id: str) -> None:
self.execution_id = execution_id
super().__init__(f"Access denied to execution '{execution_id}'")
class NotificationThrottledError(ThrottledError):
"""Raised when notification rate limit is exceeded."""
def __init__(self, user_id: str, limit: int, window_hours: int) -> None:
self.user_id = user_id
self.limit = limit
self.window_hours = window_hours
super().__init__(f"Rate limit exceeded for user '{user_id}': max {limit} per {window_hours}h")
Handler¶
configure_exception_handlers in app/core/exceptions/handlers.py registers the handlers that answer every error with the same ErrorResponse, a DomainError among them:
async def domain_error_handler(request: Request, exc: DomainError) -> JSONResponse:
status = _map_to_status_code(exc)
return JSONResponse(ErrorResponse(status=status, detail=exc.message).model_dump(), status_code=status)
async def http_error_handler(request: Request, exc: HTTPException) -> JSONResponse:
return JSONResponse(
ErrorResponse(status=exc.status_code, detail=exc.detail).model_dump(),
status_code=exc.status_code,
headers=exc.headers,
)
async def validation_error_handler(request: Request, exc: RequestValidationError) -> JSONResponse:
detail = "; ".join(f"{error['loc'][-1]}: {error['msg']}" for error in exc.errors())
return JSONResponse(ErrorResponse(status=422, detail=detail).model_dump(), status_code=422)
async def unexpected_error_handler(request: Request, exc: Exception) -> JSONResponse:
return JSONResponse(ErrorResponse(status=500, detail="Internal server error").model_dump(), status_code=500)
def configure_exception_handlers(app: FastAPI) -> None:
app.exception_handler(DomainError)(domain_error_handler)
app.exception_handler(HTTPException)(http_error_handler)
app.exception_handler(RequestValidationError)(validation_error_handler)
# Starlette's outermost middleware sends this, then re-raises so the server still logs the traceback
app.exception_handler(Exception)(unexpected_error_handler)
def _map_to_status_code(exc: DomainError) -> int:
if isinstance(exc, NotFoundError):
return 404
if isinstance(exc, ValidationError):
return 422
if isinstance(exc, ThrottledError):
return 429
if isinstance(exc, ConflictError):
return 409
if isinstance(exc, UnauthorizedError):
return 401
if isinstance(exc, ForbiddenError):
return 403
if isinstance(exc, InvalidStateError):
return 400
if isinstance(exc, AccountLockedError):
return 423
if isinstance(exc, InfrastructureError):
return 500
return 500
The body is ErrorResponse(status, detail) from app/schemas_pydantic/common.py, the status and detail members of RFC 9457 problem details. The same body comes back for FastAPI's own HTTPExceptions, for request validation errors (detail lists field: message pairs joined by ;), for anything unexpected (a 500 with "Internal server error"; Starlette re-raises it afterwards, so the server still logs the traceback) and from the rate-limit, CSRF and request-size middlewares. create_app declares it as every route's default response, which also keeps FastAPI from documenting its own HTTPValidationError. Routes list the errors their services raise in responses={...} so they show up in the OpenAPI spec. The 401 and 403 from the current_user and admin_user dependencies mostly aren't listed, so the spec leaves them out.
Where exceptions are raised¶
Repositories return None for a missing entity. They raise only when a write breaks a constraint: UserRepository.create_user raises ConflictError on a duplicate key.
Services check for None, log, and raise the specific error. Trimmed from SavedScriptService.get_saved_script:
script = await self.saved_script_repo.get_saved_script(script_id, user_id)
if not script:
self.logger.warning("Script not found for user", user_id=user_id, script_id=script_id)
raise SavedScriptNotFoundError(script_id)
return script
The route just calls the service and returns the schema. It has no None check and no HTTPException.
Kafka handlers raise the same exceptions. No HTTP mapping applies there: the error goes up to FastStream, whose telemetry middleware records it under error_type on messaging_process_duration_seconds.
Testing¶
Tests assert on the type and its fields instead of status codes. This one is from tests/e2e/services/saved_script/test_saved_script_service.py, which gets the service from its Dishka fixture:
async def test_get_saved_script_not_found(self, saved_script_service: SavedScriptService) -> None:
user_id = _unique_user_id()
with pytest.raises(SavedScriptNotFoundError):
await saved_script_service.get_saved_script("nonexistent-script-id", user_id)
Adding one¶
Pick the base class for the status you want, put the class in the domain package's exceptions.py, export it from __init__.py, and raise it from the service. Give it a constructor if callers need the context. The handler maps it with no extra code:
# app/domain/execution/exceptions.py
class ExecutionQuotaExceededError(ThrottledError):
def __init__(self, user_id: str, current: int, limit: int) -> None:
self.user_id = user_id
self.current = current
self.limit = limit
super().__init__(f"Execution quota exceeded for user '{user_id}': {current}/{limit}")
This class is an example and doesn't exist in the code. Because it extends ThrottledError, it would come back as 429.