fastapi_faults

fastapi-faults provides typed error contracts for FastAPI, connecting Python exceptions to RFC 9457 Problem Details and OpenAPI documentation. Its core idea is that every application error has one immutable definition, used consistently for exception handling, application/problem+json responses, and generated OpenAPI schemas. The project aims to avoid duplicated responses dictionaries, process-global registries, and drift between documented and actual endpoint errors. Core concepts are Fault and FaultRegistry. A Fault maps a domain exception to fields such as status, stable code, title, detail, headers, examples, and schemas. A feature can define a small FaultRegistry beside its code, and the application composes registries explicitly with FaultRegistry.merge. Definitions are immutable, merge order is deterministic, and conflicting exception classes, codes, type URIs, or schema names fail during configuration. The type_base option derives a stable problem type URI from each fault code; a fault may instead provide an explicit type. Installation fails when a domain fault has neither, which keeps incomplete contracts out of a running application. Routes use FastAPI's standard APIRouter, and registry.responses(...) generates the responses metadata for declared faults. The library does not subclass or replace APIRouter. Declared faults must belong to the registry installed on the application. RFC 9457 extension members can be typed with Pydantic models: an extensions_model validates custom problem fields, and an extensions callable produces values, with the generated problem schema describing those members. Installing a registry can normalize framework failures by default. Request validation becomes a 422 Problem Details response with stable, location-aware errors. HTTPException and routing errors receive matching Problem Details responses. Response validation and unexpected exceptions become safe internal-error responses. Installation options include include_validation_error, include_http_exceptions, and include_unhandled_error. Testing helpers live in the repository's tests/helpers.py and are not shipped with the library. Within a checkout they can assert runtime and documentation drift through functions such as assert_no_undeclared_faults, assert_openapi_contract, and assert_problem. The undeclared-fault monitor must be entered before the application's first request. Requirements are CPython 3.12, 3.13, or 3.14; FastAPI 0.115 or newer below 1.0; and Pydantic 2.9 or newer below 3.0. Installation is via pip install fastapi_faults. Development uses uv sync --all-groups and quality gates run ruff format --check, ruff check, mypy, pytest, and uv build. Runnable examples are in examples/minimal and examples/namespaced. The project is released under the MIT License.