v1.0.1

Fixed

• A Raises marker shared through a PEP 695 type alias and placed as a metadata element of Annotated (Annotated[Item, CommonRaises, Raises[...]]) is no longer dropped silently — the alias is now unwrapped in metadata position too, on par with tuple unpacking. Aliasing the whole annotation already worked.

Full changelog: https://feodor-ra.github.io/fastapi-typed-errors/changelog/

v1.0.0

First stable release. Typed HTTP errors for FastAPI — exact Literal error codes in OpenAPI, discriminated oneOf unions on the code field, and a single source of truth: the error class itself.

In plain FastAPI, raise HTTPException(404, "...") buries the error code in a string. This package makes an error a class whose HTTP status, machine-readable code and response model are declared once and derived automatically — so your error contract is typed, self-documenting, and verifiable in CI.

Highlights — three independent layers, adopt only what you need

• core — model an error as a class. BaseError[Literal[...]] derives its HTTP status, machine-readable code and Pydantic response model once, via a metaclass. Wire the single handler the FastAPI way: app.add_exception_handler(BaseError, handle_base_error). error_models() builds discriminated oneOf unions, so Swagger UI shows a per-code variant picker.
• decorator — with_errors(router) + Raises[...] in the return annotation fill responses={} for you. An in-place router patch preserves object identity, so include_router, websockets and app-level decorators keep working natively. with_errors(router, auto=True) discovers raised errors statically — no markers at all.
• analysis — check_raises(app) verifies that what each route declares matches what it can actually raise (endpoint + full dependency tree). Ships a CLI for CI: fastapi-typed-errors check app.main:app (via the cli extra).

Install

pip install fastapi-typed-errors          # core + decorator
pip install "fastapi-typed-errors[cli]"   # + the CI-checker CLI

Requirements

• Python 3.12+
• FastAPI ≥ 0.115 (excluding 0.137.* / 0.138.*)
• Pydantic ≥ 2.9

Quality

Fully typed (py.typed), 100% branch-covered, linted with ruff and type-checked with ty at maximum strictness; tested across Python 3.12 / 3.13 / 3.14 and against the FastAPI floor.

Documentation

📖 https://feodor-ra.github.io/fastapi-typed-errors/ — guide, customization, limitations, and an auto-generated API reference (English and Russian).