FastAPI Manejo de errores
En el desarrollo de API, es necesario devolver información de error al cliente. FastAPI proporcionaHTTPExceptionpara lanzar errores HTTP, y también admite manejadores de excepciones personalizados para manejar escenarios de error más complejos.
Usando HTTPException
Cuando necesite devolver una respuesta de error, lanceHTTPException:
Ejemplo
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:
# Cuando el recurso no existe, lanza un error 404
raise HTTPException(status_code=404, detail="Item not found")
return {"item": items[item_id]}
Al acceder ahttp://127.0.0.1:8000/items/42devuelve:
{
"detail": "Item not found"
}
El código de estado HTTP es404。
Tenga en cuenta que aquí se usa
raiseen lugar dereturn。HTTPExceptiones una excepción; cuando se lanza, FastAPI la captura y devuelve la respuesta de error HTTP correspondiente. Esto es consistente con el mecanismo de manejo de excepciones de Python.
Parámetros de HTTPException
| Parámetro | Tipo | Descripción |
|---|---|---|
status_code | int | Código de estado HTTP (obligatorio) |
detail | Any | Detalles del error, puede ser una cadena, diccionario, lista, etc. |
headers | dict | None | Encabezados de respuesta adicionales (opcional) |
Detalles de error personalizados
detailEl parámetro puede ser de cualquier tipo, no limitado a cadenas:
Ejemplo
app = FastAPI()
@app.get("/items/{item_id}")
async def read_item(item_id: str):
if item_id == "invalid":
# detail puede ser un diccionario, que contiene más información de error
raise HTTPException(
status_code=400,
detail={
"error_code": "INVALID_ID",
"message": "El formato del ID del producto es incorrecto",
"hint": "Utilice un ID que combine letras y números"
}
)
return {"item_id": item_id}
Agregar encabezados de respuesta personalizados
En ciertos escenarios, es necesario agregar encabezados de respuesta personalizados en la respuesta de error:
Ejemplo
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="Item not found",
headers={"X-Error": "There goes my error"}, # Encabezados de respuesta personalizados
)
return {"item": item_id}
En escenarios donde se necesita limitar la frecuencia de solicitudes del cliente (limitación de velocidad), puede agregar el encabezado
Retry-Afteren el encabezado de respuesta de error, para indicar al cliente cuándo puede reintentar.
Manejador de excepciones personalizado
Puede registrar manejadores para excepciones personalizadas o excepciones integradas, para unificar el formato de las respuestas de error:
Ejemplo
from fastapi.responses import JSONResponse
# Clase de excepción personalizada
class UnicornException(Exception):
def __init__(self, name: str):
self.name = name
app = FastAPI()
# Registrar el manejador de excepciones
@app.exception_handler(UnicornException)
async def unicorn_exception_handler(request: Request, exc: UnicornException):
# Devolver una respuesta de error con formato personalizado
return JSONResponse(
status_code=418,
content={"message": f"Oops! {exc.name} did something wrong"},
)
@app.get("/unicorns/{name}")
async def read_unicorn(name: str):
if name == "yolo":
# Lanzar una excepción personalizada
raise UnicornException(name=name)
return {"unicorn_name": name}
Sobrescribir el manejador de excepciones predeterminado
FastAPI tiene manejadores de excepciones predeterminados; puede sobrescribirlos para personalizar el formato de las respuestas de error:
Ejemplo
from fastapi.responses import JSONResponse
from fastapi.exceptions import RequestValidationError
from starlette.exceptions import HTTPException as StarletteHTTPException
app = FastAPI()
# Sobrescribir el manejador de excepciones HTTP
@app.exception_handler(StarletteHTTPException)
async def http_exception_handler(request: Request, exc: StarletteHTTPException):
return JSONResponse(
status_code=exc.status_code,
content={"error": f"HTTP error: {exc.detail}"},
)
# Sobrescribir el manejador de excepciones de validación de solicitudes
@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
return JSONResponse(
status_code=422,
content={"error": "Falló la validación de datos", "details": exc.errors()},
)
RequestValidationErrores la excepción que FastAPI lanza cuando falla la validación de los datos de la solicitud. Sobrescribir su manejador permite personalizar el formato de respuesta de los errores de validación.
Redirección
UsandoRedirectResponsepara implementar redirección:
Ejemplo
from fastapi.responses import RedirectResponse
app = FastAPI()
@app.get("/items/")
async def read_items():
return {"items": ["foo", "bar"]}
@app.get("/redirect")
async def redirect():
# Redirigir a /items/
return RedirectResponse(url="/items/")
Encabezados de respuesta y códigos de estado personalizados
UsandoJSONResponsepara personalizar encabezados de respuesta y códigos de estado:
Ejemplo
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)
Resumen
- Usar
raise HTTPExceptionpara devolver respuestas de error HTTP detailEl parámetro detail puede ser de cualquier tipo (cadena, diccionario, lista, etc.)- Usar
@app.exception_handlerpara registrar manejadores de excepciones personalizados - Se pueden sobrescribir los manejadores de excepciones predeterminados de FastAPI para unificar el formato de errores
- Usar
RedirectResponsepara implementar redirección