Exception Handling

The framework provides a centralized ExceptionHandler that handles reporting (logging) and rendering (HTTP responses) for exceptions across both web and CLI contexts.

Overview

ExceptionHandler
├── report()    — logs/tracks the exception
└── render()    — converts the exception into an HTTP response

handle() is the main entry point called by FastAPI. It calls both report() and render() in sequence.

Setup

Pass a custom handler class when creating your Application:

# bootstrap/application.py
from fastapi_startkit import Application
from fastapi_startkit.exceptions import ExceptionHandler as BaseHandler
from starlette.responses import RedirectResponse

class ExceptionHandler(BaseHandler):
    def register(self):
        self.register_render(
            NotAuthenticated,
            lambda request, exc: RedirectResponse(url="/login", status_code=303),
        )

app = Application(
    base_path=...,
    exception_handler=ExceptionHandler,
)

register() is called automatically during application boot. Wire your renders and reports there.

Registering Renders

A render callable converts an exception into a Starlette/FastAPI Response.

# Signature: (request, exc) -> Response
def register(self):
    self.register_render(
        PaymentRequiredException,
        lambda request, exc: JSONResponse({"error": str(exc)}, status_code=402),
    )

Renders are matched by exact type. If no render is found for the exception, render() returns None and FastAPI falls back to its own default error handling.

Registering Reports

Custom reporters let you send exceptions to external services (Sentry, Datadog, etc.):

def register(self):
    self.register_report(
        Exception,
        lambda exc: sentry_sdk.capture_exception(exc),
    )

Suppressing Reports

Use dont_report() to skip logging for expected exceptions (e.g. 404s, auth redirects):

def register(self):
    self.dont_report([NotAuthenticated, ModelNotFoundException])

Handler Objects

For complex logic, register a handler object that implements report(exc) and/or render(request, exc):

class MyHandler:
    def report(self, exc):
        sentry_sdk.capture_exception(exc)

    async def render(self, request, exc):
        return JSONResponse({"error": str(exc)}, status_code=500)

def register(self):
    self.register_handler(MyException, MyHandler())

Handler objects support MRO resolution — a handler registered for Exception will also match subclasses unless a more specific handler exists.

How It Wires to FastAPI

FastAPIProvider.boot() registers a catch-all exception handler on the FastAPI instance:

# Happens automatically — no action needed
self.app.fastapi.add_exception_handler(Exception, handler)

This means every unhandled exception in a request is passed through exception_manager.handle(exc, {"request": request}).

CLI Context

In CLI (non-HTTP) contexts, install() wires sys.excepthook to call report() directly. The render path is never reached because there is no HTTP request. KeyboardInterrupt is passed through to the default hook unchanged.

Built-in Exception Types

The framework ships several typed exceptions in fastapi_startkit.exceptions:

Exception	Status
ModelNotFoundException	404
AuthorizationException	403
RouteNotFoundException	404
MethodNotAllowedException	405
ThrottleRequestsException	429

These carry get_status(), get_response(), and optionally get_headers() methods that your render callables can use:

self.register_render(
    ModelNotFoundException,
    lambda req, exc: JSONResponse(
        {"error": exc.get_response()},
        status_code=exc.get_status(),
    ),
)