fastapi-typed-errors¶

Typed HTTP errors for FastAPI. Exact Literal codes in OpenAPI, discriminated oneOf unions on the code field, and a single source of truth the error class itself.

Why¶

In plain FastAPI an error is HTTPException(404, "..."). The error code lives in a string, OpenAPI has neither a code type nor a response-body model, and the list of errors a route can raise has to be duplicated by hand into responses={}. Clients can't switch on the code, and the docs drift away from the code fast.

fastapi-typed-errors makes an error a class: the HTTP status, machine-readable code and response model are declared once and derived automatically.

@app.get("/items/{item_id}")
def get_item(item_id: int):
    if item_id == 0:
        raise HTTPException(404, "No item")  # (1)!
    return {"item_id": item_id}

class NotFoundError(BaseError[Literal[ErrorCode.NOT_FOUND]]):
    http_status = HTTPStatus.NOT_FOUND


@router.get("/items/{item_id}")
def get_item(item_id: int) -> Annotated[Item, Raises[NotFoundError]]:  # (1)!
    if item_id == 0:
        raise NotFoundError("No item")
    return Item(item_id=item_id)

router = with_errors(APIRouter(), auto=True)  # (1)!


@router.get("/items/{item_id}")
def get_item(item_id: int) -> Item:  # (2)!
    if item_id == 0:
        raise NotFoundError("No item")
    return Item(item_id=item_id)

The error response body is always predictable:

{ "code": "NOT_FOUND", "detail": "No item" }

And in OpenAPI the route gets one entry per status with an exact code and a body model. Here is how it renders in Swagger UI:

[Swagger UI Responses panel: 200 Item, 403 ErrorResponse[FORBIDDEN], 404 oneOf of ErrorResponse[NOT_FOUND] / ErrorResponse[GONE] discriminated by code]

Features¶

Install¶

uv add fastapi-typed-errors
# with the CLI for the CI check:
uv add "fastapi-typed-errors[cli]"

pip install fastapi-typed-errors
pip install "fastapi-typed-errors[cli]"

Next¶