Как обрабатывать ошибки и HTTPException в FastAPI

Как обрабатывать ошибки и возвращать HTTP-исключения?

Для ожидаемых ошибок API в FastAPI используют HTTPException. Его нужно не возвращать, а выбрасывать через raise; FastAPI остановит обработку запроса и сформирует HTTP-ответ с указанным статусом и полем detail.

Подробный ответ

Что такое HTTPException

HTTPException — специальное исключение FastAPI для передачи ошибки клиенту. В нём указывают HTTP status code и описание ошибки.

from fastapi import FastAPI, HTTPException

app = FastAPI()


@app.get('/articles/{article_id}')
def get_article(article_id: int):
    article = find_article(article_id)
    if article is None:
        raise HTTPException(
            status_code=404,
            detail='Article not found',
        )
    return article

Почему используется raise

Исключение нужно выбросить через raise, а не вернуть через return. Тогда FastAPI немедленно завершит обработку текущего запроса и не продолжит выполнять оставшийся код endpoint.

Частые HTTP-статусы

400 Bad Request — некорректный запрос;
401 Unauthorized — пользователь не аутентифицирован;
403 Forbidden — пользователь аутентифицирован, но не имеет прав;
404 Not Found — ресурс не найден;
409 Conflict — конфликт состояния, например дублирующая запись;
422 Unprocessable Content — данные не прошли валидацию.

Глобальные обработчики

Для собственных исключений можно зарегистрировать exception handler. Это помогает возвращать единый формат ошибок и не повторять обработку в каждом endpoint.

from fastapi import Request
from fastapi.responses import JSONResponse


class DomainError(Exception):
    pass


@app.exception_handler(DomainError)
async def domain_error_handler(request: Request, exc: DomainError):
    return JSONResponse(
        status_code=400,
        content={'detail': str(exc)},
    )

Как ответить на собеседовании

Для ожидаемых ошибок я выбрасываю HTTPException с нужным статусом и detail, например 404 для отсутствующего ресурса. Для доменных ошибок, которые могут возникать в разных местах, регистрирую глобальный exception handler и поддерживаю единый формат ответов.