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

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:
        # 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 usaraiseen 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ámetroTipoDescripción
status_codeintCódigo de estado HTTP (obligatorio)
detailAnyDetalles del error, puede ser una cadena, diccionario, lista, etc.
headersdict | NoneEncabezados de respuesta adicionales (opcional)

Detalles de error personalizados

detailEl parámetro puede ser de cualquier tipo, no limitado a cadenas:

Ejemplo

from fastapi import FastAPI, HTTPException

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

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="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 encabezadoRetry-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 import FastAPI, Request
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 import FastAPI, Request
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 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():
    # 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 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)

Resumen

  • Usarraise 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
  • UsarRedirectResponsepara implementar redirección
Otras extensiones