Что такое HTTPException и как создать кастомные обработчики исключений?

Что такое HTTPException

HTTPException — встроенное исключение FastAPI (унаследованное из Starlette), которое прерывает обработку запроса и возвращает HTTP-ответ с заданным статус-кодом, телом и заголовками. Его бросают явно внутри endpoint'ов или зависимостей.

from fastapi import FastAPI, HTTPException

app = FastAPI()

@app.get("/items/{item_id}")
async def get_item(item_id: int):
    if item_id == 0:
        raise HTTPException(
            status_code=404,
            detail="Item not found",
            headers={"X-Error": "item-missing"},
        )
    return {"id": item_id}

Параметры конструктора:

• status_code — HTTP-статус ответа (обязательный)
• detail — тело ответа; может быть строкой, dict или любым JSON-сериализуемым объектом
• headers — дополнительные HTTP-заголовки ответа

HTTPException и кастомные обработчики исключений в FastAPI

Стандартный формат ответа

FastAPI по умолчанию оборачивает detail в JSON:

{"detail": "Item not found"}

Кастомный обработчик HTTPException

Чтобы изменить формат ответа для всех HTTPException, регистрируем обработчик через @app.exception_handler:

from fastapi import FastAPI, HTTPException, Request
from fastapi.responses import JSONResponse

app = FastAPI()

@app.exception_handler(HTTPException)
async def http_exception_handler(request: Request, exc: HTTPException):
    return JSONResponse(
        status_code=exc.status_code,
        content={
            "error": {
                "code": exc.status_code,
                "message": exc.detail,
                "path": str(request.url),
            }
        },
        headers=exc.headers or {},
    )

Кастомный класс исключения

Для доменных ошибок создаём собственный класс и отдельный обработчик:

class AppError(Exception):
    def __init__(self, code: str, message: str, status: int = 400):
        self.code = code
        self.message = message
        self.status = status

@app.exception_handler(AppError)
async def app_error_handler(request: Request, exc: AppError):
    return JSONResponse(
        status_code=exc.status,
        content={"error": exc.code, "message": exc.message},
    )

@app.get("/pay")
async def pay():
    raise AppError("insufficient_funds", "Not enough balance", status=402)

Обработчик ошибок валидации Pydantic

FastAPI автоматически бросает RequestValidationError при неверных входных данных. Чтобы поменять формат:

from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse

@app.exception_handler(RequestValidationError)
async def validation_error_handler(request: Request, exc: RequestValidationError):
    return JSONResponse(
        status_code=422,
        content={
            "error": "validation_error",
            "fields": [
                {
                    "loc": ".".join(str(x) for x in err["loc"]),
                    "msg": err["msg"],
                    "type": err["type"],
                }
                for err in exc.errors()
            ],
        },
    )

Глобальный обработчик всех необработанных исключений

@app.exception_handler(Exception)
async def generic_exception_handler(request: Request, exc: Exception):
    # Логируем в Sentry/stderr
    import logging
    logging.exception("Unhandled error: %s", exc)
    return JSONResponse(
        status_code=500,
        content={"error": "internal_server_error"},
    )

Подводные камни

• Если зарегистрировать кастомный обработчик HTTPException, стандартный Starlette-обработчик перестаёт работать — убедитесь, что ваш обработчик передаёт exc.headers, иначе CORS-заголовки из HTTPException пропадут.
• RequestValidationError и HTTPException — разные классы; один обработчик не покрывает оба случая.
• Обработчик глобального Exception не перехватывает ошибки в фоновых задачах (BackgroundTasks) — они логируются отдельно.
• В middleware исключения перехватываются до exception_handler'ов, поэтому HTTPException из middleware нужно обрабатывать явно внутри самого middleware.
• detail в HTTPException попадает в ответ клиенту как есть — не кладите туда внутренние детали (стектрейс, SQL-запрос).
• При использовании router'ов (APIRouter) обработчики исключений регистрируются только на уровне приложения (app), не на роутере.

• Описывать httpexception handlers только как термин и не показывать механизм на минимальном примере.
• Игнорировать ошибки, пустые данные, конкурентный доступ или границы транзакции.
• Не связывать поведение с официальным контрактом FastAPI и реальной эксплуатацией.

• Объясняет httpexception handlers через последовательность действий, а не через набор ключевых слов.
• Приводит короткий кодовый пример или production-сценарий с ожидаемым поведением.
• Называет хотя бы один риск: производительность, безопасность, транзакции, память или сопровождение.