FastAPI exception handler: единый формат ошибок
@app.exception_handler перехватывает выбранное исключение и возвращает собственный HTTP-ответ. Это позволяет отдавать единый JSON ошибки, добавлять код запроса и не раскрывать стек клиенту. Обработчик должен быть асинхронным и возвращать Response, а не выбрасывать исключение дальше.
Вернуть 404 для своего исключения
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.
Переопределить ошибку валидации
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.