Обработка ошибок в FastAPI
При разработке API необходимо возвращать клиенту информацию об ошибках. FastAPI предоставляетHTTPExceptionвозможность вызывать HTTP-ошибки, а также поддерживает пользовательские обработчики исключений для обработки более сложных сценариев ошибок.
Используйте HTTPException
Когда нужно вернуть ответ об ошибке, raiseHTTPException:
Пример
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_code | int | Код состояния HTTP (обязательно) |
detail | Any | Детали ошибки могут быть строкой, словарём, списком и т. д. |
headers | dict | None | Дополнительные заголовки ответа (необязательно) |
Пользовательские детали ошибки
detailПараметр может быть любого типа, не ограничиваясь строками:
Пример
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}
Добавление пользовательских заголовков ответа
В некоторых сценариях необходимо добавить пользовательские заголовки ответа в ответ об ошибке:
Пример
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.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.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.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.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Реализовать перенаправление