Respuestas y códigos de estado

Códigos más comunes (200, 201, 404, 400)

Los códigos de estado HTTP son números de tres dígitos que el servidor envía al cliente para indicar el resultado de una petición. En el desarrollo de APIs REST con FastAPI, cuatro códigos cubren la mayoría de situaciones que encontrarás en aplicaciones básicas.

Código 200 - OK

El código 200 es el más utilizado y significa que la petición se procesó correctamente. FastAPI lo devuelve automáticamente cuando una función de ruta se ejecuta sin errores y retorna datos.

from fastapi import FastAPI

app = FastAPI()

@app.get("/usuarios/{user_id}")
def obtener_usuario(user_id: int):
    # Simulamos obtener un usuario
    usuario = {"id": user_id, "nombre": "Ana García", "email": "ana@email.com"}
    return usuario  # FastAPI devuelve automáticamente código 200

Cuando accedes a /usuarios/1, el servidor responde con código 200 y los datos del usuario. Este código se usa para operaciones de lectura exitosas y actualizaciones que no crean recursos nuevos.

Código 201 - Created

El código 201 indica que se creó un nuevo recurso exitosamente. A diferencia del 200, este código comunica específicamente que algo nuevo existe en el servidor tras la petición.

from fastapi import FastAPI, status

app = FastAPI()

@app.post("/usuarios", status_code=status.HTTP_201_CREATED)
def crear_usuario(nombre: str, email: str):
    # Simulamos crear un usuario nuevo
    nuevo_usuario = {
        "id": 123,
        "nombre": nombre,
        "email": email,
        "creado": "2024-01-15T10:30:00"
    }
    return nuevo_usuario

El parámetro status_code en el decorador especifica que FastAPI debe devolver 201 en lugar del 200 por defecto. Este código es fundamental en operaciones POST que crean recursos.

Código 404 - Not Found

El código 404 señala que el recurso solicitado no existe. En APIs REST, esto ocurre frecuentemente cuando se busca un elemento por ID que no está en la base de datos.

from fastapi import FastAPI, HTTPException, status

app = FastAPI()

# Simulamos una base de datos simple
usuarios_db = {
    1: {"id": 1, "nombre": "Carlos López"},
    2: {"id": 2, "nombre": "María Rodríguez"}
}

@app.get("/usuarios/{user_id}")
def obtener_usuario(user_id: int):
    if user_id not in usuarios_db:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Usuario no encontrado"
        )
    return usuarios_db[user_id]

La clase HTTPException permite lanzar errores HTTP específicos. El parámetro detail proporciona información adicional sobre el error que será incluida en la respuesta JSON.

Código 400 - Bad Request

El código 400 indica que la petición contiene errores de formato, datos inválidos o parámetros incorrectos. Es el código genérico para errores del cliente.

from fastapi import FastAPI, HTTPException, status

app = FastAPI()

@app.post("/usuarios")
def crear_usuario(nombre: str, edad: int):
    # Validación básica de datos
    if not nombre or len(nombre.strip()) == 0:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="El nombre no puede estar vacío"
        )
    
    if edad < 0 or edad > 120:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="La edad debe estar entre 0 y 120 años"
        )
    
    # Si los datos son válidos, crear el usuario
    nuevo_usuario = {"nombre": nombre, "edad": edad}
    return nuevo_usuario

Este código es especialmente útil para validaciones personalizadas que van más allá de lo que Pydantic puede manejar automáticamente. Cuando los datos no cumplen las reglas de negocio, el código 400 comunica claramente que el problema está en la petición del cliente.

Uso del módulo status

FastAPI incluye el módulo status que contiene constantes para todos los códigos HTTP. Usar estas constantes hace el código más legible y reduce errores de escritura.

from fastapi import status

# En lugar de números mágicos
status_code=200  # Menos claro

# Usa las constantes
status_code=status.HTTP_200_OK  # Más descriptivo
status_code=status.HTTP_201_CREATED
status_code=status.HTTP_404_NOT_FOUND
status_code=status.HTTP_400_BAD_REQUEST

Estas constantes mejoran la mantenibilidad del código y hacen que las intenciones sean más claras para otros desarrolladores que lean tu código.

Cuándo usar cada código de estado

La elección del código de estado correcto depende del tipo de operación y del resultado obtenido. Cada código comunica información específica al cliente sobre qué ocurrió con su petición, permitiendo que las aplicaciones frontend manejen las respuestas de manera apropiada.

Criterios para código 200

Utiliza el código 200 cuando una operación se completa exitosamente sin crear nuevos recursos. Este código es apropiado para:

• Consultas de datos que devuelven información existente
• Actualizaciones que modifican recursos sin crear nuevos elementos
• Operaciones de procesamiento que no alteran el estado de los recursos

from fastapi import FastAPI

app = FastAPI()

@app.get("/productos")
def listar_productos():
    # Devuelve lista de productos existentes
    return [{"id": 1, "nombre": "Laptop"}, {"id": 2, "nombre": "Mouse"}]

@app.put("/productos/{producto_id}")
def actualizar_producto(producto_id: int, nombre: str, precio: float):
    # Modifica un producto existente
    producto_actualizado = {
        "id": producto_id,
        "nombre": nombre,
        "precio": precio,
        "actualizado": True
    }
    return producto_actualizado  # Código 200 automático

El código 200 es la respuesta por defecto en FastAPI, por lo que no necesitas especificarlo explícitamente en estos casos.

Criterios para código 201

Reserva el código 201 exclusivamente para operaciones que crean nuevos recursos en el servidor. La diferencia clave con el 200 es que algo nuevo existe después de la petición:

from fastapi import FastAPI, status

app = FastAPI()

@app.post("/pedidos", status_code=status.HTTP_201_CREATED)
def crear_pedido(cliente_id: int, productos: list):
    # Crea un nuevo pedido en el sistema
    nuevo_pedido = {
        "id": 456,
        "cliente_id": cliente_id,
        "productos": productos,
        "estado": "pendiente",
        "fecha_creacion": "2024-01-15T14:30:00"
    }
    return nuevo_pedido

@app.post("/categorias", status_code=status.HTTP_201_CREATED)
def crear_categoria(nombre: str, descripcion: str):
    # Añade una nueva categoría al catálogo
    nueva_categoria = {
        "id": 789,
        "nombre": nombre,
        "descripcion": descripcion
    }
    return nueva_categoria

Es importante especificar explícitamente el código 201 porque FastAPI devuelve 200 por defecto, incluso en operaciones POST.

Criterios para código 404

Aplica el código 404 cuando el cliente solicita un recurso específico que no existe. Este código debe usarse únicamente para recursos que se buscan por identificador:

from fastapi import FastAPI, HTTPException, status

app = FastAPI()

# Base de datos simulada
productos_db = {1: {"nombre": "Laptop"}, 2: {"nombre": "Mouse"}}

@app.get("/productos/{producto_id}")
def obtener_producto(producto_id: int):
    if producto_id not in productos_db:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail=f"Producto con ID {producto_id} no encontrado"
        )
    return productos_db[producto_id]

@app.delete("/productos/{producto_id}")
def eliminar_producto(producto_id: int):
    if producto_id not in productos_db:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="No se puede eliminar un producto que no existe"
        )
    del productos_db[producto_id]
    return {"mensaje": "Producto eliminado correctamente"}

No uses 404 para listas vacías o consultas sin resultados. Una búsqueda que no encuentra elementos debe devolver 200 con una lista vacía.

Criterios para código 400

Emplea el código 400 cuando la petición contiene errores que impiden su procesamiento. Este código abarca varios escenarios de error del cliente:

Datos con formato incorrecto:

from fastapi import FastAPI, HTTPException, status
import re

app = FastAPI()

@app.post("/usuarios")
def crear_usuario(email: str, telefono: str):
    # Validar formato de email
    patron_email = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
    if not re.match(patron_email, email):
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="Formato de email inválido"
        )
    
    # Validar formato de teléfono
    if not telefono.isdigit() or len(telefono) != 9:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="El teléfono debe tener exactamente 9 dígitos"
        )
    
    return {"email": email, "telefono": telefono}

Violación de reglas de negocio:

@app.post("/transferencias")
def crear_transferencia(cuenta_origen: int, cuenta_destino: int, cantidad: float):
    if cuenta_origen == cuenta_destino:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="La cuenta origen y destino no pueden ser la misma"
        )
    
    if cantidad <= 0:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="La cantidad debe ser mayor que cero"
        )
    
    # Procesar transferencia
    return {"transferencia_id": 123, "estado": "procesada"}

Patrones de decisión

Para elegir el código correcto, hazte estas preguntas en orden:

• ¿La petición tiene errores? → Usa 400
• ¿El recurso específico no existe? → Usa 404
• ¿Se creó algo nuevo? → Usa 201
• ¿La operación fue exitosa? → Usa 200

Este flujo de decisión te ayudará a mantener consistencia en tu API y proporcionar respuestas claras a los clientes que consuman tus endpoints.