FastAPI maneja errores lanzando excepciones que convierte en respuestas HTTP apropiadas. HTTPException cubre la mayoría de los casos; los controladores de excepciones personalizados te permiten controlar el formato de errores globalmente.
fastapi HTTPException
():
item = db.get()
item:
HTTPException(status_code=, detail=)
item.is_public:
HTTPException(status_code=, detail=)
item
raise HTTPException(status_code=..., detail=...) es la forma idiomática de devolver un error — FastAPI produce una respuesta JSON {"detail": "..."} con el estado especificado. El detail puede ser cualquier valor serializable a JSON (cadena, dict, lista).
When request data fails Pydantic validation, FastAPI AUTOMATICALLY returns a 422
with a structured list of exactly which fields are wrong — you write nothing.
from fastapi import Request
from fastapi.responses import JSONResponse
class ItemNotFound(Exception):
def __init__(self, item_id: int): self.item_id = item_id
@app.exception_handler(ItemNotFound) # handle a custom exception type globally
def handle_not_found(request: Request, exc: ItemNotFound):
return JSONResponse(status_code=404, content={"error": f"Item {exc.item_id} not found"})
@app.get("/items/{id}")
def get(id: int):
raise ItemNotFound(id) # raise your domain exception; the handler formats it
Los controladores de excepciones personalizados te permiten mapear tus propias excepciones (de dominio) a respuestas, centralizando el formato de errores y manteniendo el código del controlador limpio.
from fastapi.exceptions import RequestValidationError
@app.exception_handler(RequestValidationError) # customize the 422 validation-error format
def validation_handler(request, exc):
return JSONResponse(status_code=422, content={"errors": exc.errors()})
El manejo adecuado de errores es esencial para construir APIs confiables y profesionales, y el enfoque de FastAPI es limpio y coherente.
La HTTPException idiomática facilita devolver respuestas de error correctas con códigos de estado y mensajes apropiados — fundamental para cualquier endpoint que pueda fallar (no encontrado, prohibido, estado incorrecto).
Igualmente valioso es que los errores de validación se manejen automáticamente (los fallos de Pydantic producen respuestas 422 estructuradas sin código de tu parte), y que los controladores de excepciones personalizados te permitan mapear tus propias excepciones de dominio a respuestas y aplicar un formato de error consistente en toda la API — mejorando tanto la mantenibilidad (lógica de errores centralizada) como la experiencia del cliente (formas de error predecibles).
Comprender HTTPException, errores de validación automáticos y controladores personalizados cubre el espectro práctico del manejo de errores, convirtiéndolo en conocimiento importante para construir APIs robustas.