fastapi-error-handler

Elegant, consistent error handling for FastAPI — one line setup

The Problem

Every FastAPI app needs error handling. Without it, your API returns inconsistent, ugly responses:

{"detail": "Not Found"}
{"detail": [{"loc": ["body", "email"], "msg": "field required", "type": "value_error.missing"}]}
500 Internal Server Error

Different formats, missing context, no error codes. Your frontend team hates you.

The Solution

pip install fastapi-error-handler

from fastapi import FastAPI
from fastapi_error_handler import setup_error_handlers

app = FastAPI()
setup_error_handlers(app)  # That's it.

Now every error returns a clean, consistent JSON response:

{
    "error": "not_found",
    "message": "User with id '123' not found",
    "status": 404,
    "path": "/users/123"
}

Built-in Exceptions

Raise these anywhere in your routes — they automatically produce the right HTTP response:

from fastapi_error_handler import (
    NotFoundError,      # 404
    BadRequestError,    # 400
    UnauthorizedError,  # 401
    ForbiddenError,     # 403
    ConflictError,      # 409
    ValidationError,    # 422
    RateLimitError,     # 429
    InternalError,      # 500
)

@app.get("/users/{id}")
async def get_user(id: int):
    user = await db.get_user(id)
    if not user:
        raise NotFoundError("User", id=str(id))
    return user

@app.post("/users")
async def create_user(email: str):
    if await db.email_exists(email):
        raise ConflictError("A user with this email already exists")
    ...

What Gets Handled

Configuration

setup_error_handlers(
    app,
    log_errors=True,       # Log 4xx as WARNING, 5xx as ERROR
    include_path=True,     # Include request path in response
    on_error=my_callback,  # Custom callback on every error
)

Custom Error Callback

def send_to_sentry(request, exc):
    sentry_sdk.capture_exception(exc)

setup_error_handlers(app, on_error=send_to_sentry)

Custom Exceptions

Extend AppError for domain-specific errors:

from fastapi_error_handler import AppError

class InsufficientBalanceError(AppError):
    status_code = 402
    error_code = "insufficient_balance"

    def __init__(self, balance: float, required: float):
        super().__init__(
            message=f"Insufficient balance: have {balance}, need {required}",
            details={"balance": balance, "required": required},
        )

Response Format

Every error response follows this schema:

{
    "error": "string",       // machine-readable error code
    "message": "string",     // human-readable message
    "status": 404,           // HTTP status code
    "path": "/users/123",    // request path (optional)
    "details": {}            // additional context (optional)
}

License

MIT