FastAPI exception handler: единый формат ошибок

Категория: Backend · Язык: Python · Обновлено:

@app.exception_handler перехватывает выбранное исключение и возвращает собственный HTTP-ответ. Это позволяет отдавать единый JSON ошибки, добавлять код запроса и не раскрывать стек клиенту. Обработчик должен быть асинхронным и возвращать Response, а не выбрасывать исключение дальше.

Вернуть 404 для своего исключения

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

app = FastAPI()

class ItemNotFound(Exception):
    def __init__(self, item_id: int):
        self.item_id = item_id

@app.exception_handler(ItemNotFound)
async def item_not_found_handler(request: Request, exc: ItemNotFound):
    return JSONResponse(
        status_code=404,
        content={"error": "not_found", "item_id": exc.item_id},
    )

@app.get("/items/{item_id}")
async def get_item(item_id: int):
    raise ItemNotFound(item_id)

ItemNotFound — обычное исключение; FastAPI ищет обработчик по типу и вызывает его. Ответ получает заданный статус и тело; заголовки можно добавить через headers=. Если обработчик не зарегистрирован, исключение превратится в 500.

Переопределить ошибку валидации

Python
from fastapi import FastAPI, Request
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse

app = FastAPI()

@app.exception_handler(RequestValidationError)
async def validation_handler(request: Request, exc: RequestValidationError):
    return JSONResponse(
        status_code=422,
        content={"error": "validation", "details": exc.errors()},
    )

@app.get("/items/{item_id}")
async def get_item(item_id: int):
    return {"id": item_id}

RequestValidationError возникает, когда путь, query или тело не прошли проверку Pydantic. exc.errors() содержит список проблем; в ответе не стоит отдавать внутренние имена классов и пути. Для production оставьте понятные поля loc, msg, type.

Обработчик Exception — последний рубеж: он ловит необработанные ошибки, но не должен подменять нормальную обработку. Логируйте исключение с request ID, а клиенту возвращайте общий internal_error. В тестах с TestClient для проверки такого обработчика может понадобиться raise_server_exceptions=False.

Специфичные обработчики имеют приоритет над общими; регистрируйте HTTPException отдельно, только если меняете формат. Не выполняйте в обработчике тяжёлые запросы и не пытайтесь «исправить» состояние — для этого есть middleware и сервисный слой.

Документация: FastAPI exceptions, Starlette exceptions.