Exception handling

The default behaviour is good enough that people never look at it, and then every error in production is a bare 500 with a stack trace in the logs and nothing useful in the response.

What FastAPI already does

The third row is the one worth knowing: if your handler returns something that does not match response_model, FastAPI raises rather than sending it. That is a feature — a contract you publish and then violate is worse than an error — and it surprises people who expected the extra field to be dropped silently.

One error shape, applied globally

Return the same body for every failure, so clients parse one thing:

from fastapi.responses import JSONResponse

class DomainError(Exception):
    status = 400
    code = "domain_error"

    def __init__(self, detail: str):
        self.detail = detail

@app.exception_handler(DomainError)
async def domain_error(request: Request, exc: DomainError) -> JSONResponse:
    return JSONResponse(
        status_code=exc.status,
        content={
            "type": f"https://errors.example.com/{exc.code}",
            "title": exc.detail,
            "status": exc.status,
            "trace_id": request_id.get(),
        },
        media_type="application/problem+json",
    )

application/problem+json is RFC 9457 (which obsoleted 7807), and using it means clients get a machine-readable shape instead of a bespoke one per service. See Status codes.

Include the trace id in the body. A user pasting an error into a ticket then hands you the exact request, which is the difference between a five-minute investigation and an afternoon.

Subclass, do not catch-and-map

The pattern that scales is one base exception per domain concept, raised deep and handled once:

class NotFound(DomainError):
    status = 404
    code = "not_found"

class Conflict(DomainError):
    status = 409
    code = "conflict"

# Deep in the service layer. No HTTP vocabulary here.
if not order:
    raise NotFound(f"order {order_id}")

The service layer raises a domain error; the handler translates it to HTTP once. Compare with raise HTTPException(404) inside a service function, which puts HTTP knowledge in code that should not have any and makes the same function unusable from a Celery worker or a CLI.

Overriding the validation error

The default 422 body is a list of Pydantic errors, which is useful and does not match your error shape. Override it so clients see one format:

@app.exception_handler(RequestValidationError)
async def validation_error(request: Request, exc: RequestValidationError):
    return JSONResponse(
        status_code=422,
        content={
            "type": "https://errors.example.com/validation",
            "title": "Validation failed",
            "status": 422,
            "errors": [
                {"field": ".".join(str(p) for p in e["loc"][1:]), "detail": e["msg"]}
                for e in exc.errors()
            ],
        },
    )

e["loc"][1:] drops the leading "body" or "query", which is noise to a client that already knows where it put the field.

Gotcha: an exception handler registered for Exception does not catch everything. HTTPException and RequestValidationError have their own handlers registered first and win. And a handler that itself raises produces a bare 500 with no body at all, so keep them boring — no database calls, no outbound requests.

The last-resort handler

@app.exception_handler(Exception)
async def unhandled(request: Request, exc: Exception) -> JSONResponse:
    log.exception("unhandled", extra={"trace_id": request_id.get()})
    return JSONResponse(
        status_code=500,
        content={"title": "Internal error", "status": 500,
                 "trace_id": request_id.get()},
    )

Note what it does not do: never put str(exc) in the body. Exception text routinely contains a connection string, a file path or a row of data, and this is the single most common way an internal detail reaches a user.

Related

• Middleware — what runs outside the handlers
• Status codes — choosing the code
• response_model — Advanced Patterns — where ResponseValidationError comes from
• Sentry — where the traceback should go