Обработка ошибок в FastAPI

При разработке API необходимо возвращать клиенту информацию об ошибках. FastAPI предоставляетHTTPExceptionвозможность вызывать HTTP-ошибки, а также поддерживает пользовательские обработчики исключений для обработки более сложных сценариев ошибок.


Используйте HTTPException

Когда нужно вернуть ответ об ошибке, raiseHTTPException:

Пример

from fastapi import FastAPI, HTTPException

app = FastAPI()

items = {"foo": "The Foo Wrestlers", "bar": "The Bar Fighters"}


@app.get("/items/{item_id}")
async def read_item(item_id: str):
    if item_id not in items:
        # Когда ресурс не существует, вызовите ошибку 404
        raise HTTPException(status_code=404, detail="Item not found")
    return {"item": items[item_id]}

Посетитеhttp://127.0.0.1:8000/items/42При посещении вернется:

{
    "detail": "Item not found"
}

Код состояния HTTP:404。

Обратите внимание, что здесь используетсяraiseвместоreturn。HTTPException— это исключение. После его возбуждения FastAPI перехватывает его и возвращает соответствующий HTTP-ответ с ошибкой. Это соответствует механизму обработки исключений Python.


Параметры HTTPException

ПараметрTypeОписание
status_codeintКод состояния HTTP (обязательно)
detailAnyДетали ошибки могут быть строкой, словарём, списком и т. д.
headersdict | NoneДополнительные заголовки ответа (необязательно)

Пользовательские детали ошибки

detailПараметр может быть любого типа, не ограничиваясь строками:

Пример

from fastapi import FastAPI, HTTPException

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str):
    if item_id == "invalid":
        # detail может быть dict, содержащим больше информации об ошибке
        raise HTTPException(
            status_code=400,
            detail={
                "error_code": "INVALID_ID",
                "message": "Неверный формат идентификатора продукта",
                "hint": "Используйте буквенно-цифровой идентификатор"
            }
        )
    return {"item_id": item_id}

Добавление пользовательских заголовков ответа

В некоторых сценариях необходимо добавить пользовательские заголовки ответа в ответ об ошибке:

Пример

from fastapi import FastAPI, HTTPException

app = FastAPI()


@app.get("/items-header/{item_id}")
async def read_item_header(item_id: str):
    if item_id == "invalid":
        raise HTTPException(
            status_code=404,
            detail="Элемент не найден",
            headers={"X-Error": "Вот и моя ошибка"},  # Пользовательские заголовки ответа
        )
    return {"item": item_id}

В сценариях, когда нужно ограничить частоту запросов клиента (rate limiting), можно добавить в заголовки ответа об ошибкеRetry-Afterзаголовок, сообщающий клиенту, когда он может повторить попытку.


Обработчик пользовательских исключений

Вы можете зарегистрировать обработчики для пользовательских исключений или встроенных исключений, чтобы единообразно обрабатывать формат ответа об ошибке:

Пример

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


# Класс пользовательского исключения
class UnicornException(Exception):
    def __init__(self, name: str):
        self.name = name


app = FastAPI()


# Зарегистрировать обработчик исключений
@app.exception_handler(UnicornException)
async def unicorn_exception_handler(request: Request, exc: UnicornException):
    # Вернуть ответ об ошибке в пользовательском формате
    return JSONResponse(
        status_code=418,
        content={"message": f"Упс! {exc.name} сделал что-то не так"},
    )


@app.get("/unicorns/{name}")
async def read_unicorn(name: str):
    if name == "yolo":
        # Вызвать пользовательское исключение
        raise UnicornException(name=name)
    return {"unicorn_name": name}

Переопределить обработчик исключений по умолчанию

FastAPI имеет обработчики исключений по умолчанию. Вы можете переопределить их, чтобы настроить формат ответа об ошибке:

Пример

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from fastapi.exceptions import RequestValidationError
from starlette.exceptions import HTTPException as StarletteHTTPException

app = FastAPI()


# Переопределить обработчик HTTP-исключений
@app.exception_handler⟦⟧StarletteHTTPException(StarletteHTTPException)
async def http_exception_handler(request: Request, exc: StarletteHTTPException):
    return JSONResponse(
        status_code=exc.status_code,
        content={"error": f"Ошибка HTTP: {exc.detail}"},
    )


# Переопределить обработчик исключения валидации запроса
@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
    return JSONResponse(
        status_code=422,
        content={"error": "Ошибка валидации данных", "details": exc.errors()},
    )

RequestValidationError— это исключение, которое FastAPI выбрасывает, когда проверка данных запроса не проходит. Переопределение его обработчика позволяет настроить формат ответа для ошибок валидации.


Redirect

ИспользованиеRedirectResponseРеализуйте перенаправление:

Пример

from fastapi import FastAPI
from fastapi.responses import RedirectResponse

app = FastAPI()


@app.get("/items/")
async def read_items():
    return {"items": ["foo", "bar"]}


@app.get("/redirect")
async def redirect():
    # Перенаправить на /items/
    return RedirectResponse(url="/items/")

Пользовательские заголовки ответа и код состояния

ИспользованиеJSONResponseПользовательские заголовки ответа и код состояния:

Пример

from fastapi import FastAPI
from fastapi.responses import JSONResponse

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: int):
    content = {"item_id": item_id}
    headers = {"X-Custom-Header": "custom-header-value"}
    return JSONResponse(content=content, headers=headers)

Итог

  • Использованиеraise HTTPExceptionВернуть HTTP-ответ с ошибкой
  • detailПараметр может быть любого типа (строка, словарь, список и т. д.)
  • Использование@app.exception_handlerЗарегистрировать пользовательский обработчик исключений
  • Вы можете переопределить стандартные обработчики исключений FastAPI, чтобы унифицировать формат ошибок.
  • ИспользованиеRedirectResponseРеализовать перенаправление
Другие расширения