BackgroundTasks programa una función para ejecutarse después de enviar la respuesta. Sirve para acciones pequeñas en el mismo proceso, como una notificación sencilla, cuando el cliente no necesita esperar.
from fastapi import BackgroundTasks, FastAPI, status
app = FastAPI()
def enviar_confirmacao(pedido_id: int) -> None:
print(f"confirmar pedido {pedido_id}")
@app.post("/pedidos/{pedido_id}", status_code=status.HTTP_202_ACCEPTED)
async def criar_pedido(
pedido_id: int,
tarefas: BackgroundTasks,
) -> dict[str, int]:
tarefas.add_task(enviar_confirmacao, pedido_id)
return {"pedido_id": pedido_id}La función puede ser síncrona o asíncrona y recibe argumentos mediante add_task(). HTTP 202 significa aceptado, no completado. Devuelve un identificador y ofrece estado cuando el resultado posterior forma parte del contrato.
Buenas prácticas
No trates BackgroundTasks como cola durable. Los reinicios pueden perder trabajo y varias réplicas no comparten estado. Usa Celery u otro sistema persistente para retry, programación, carga alta o ejecución distribuida. Diseña tareas idempotentes y registra fallos sin datos sensibles.
Consulta Celery en Python para colas persistentes y inyección de dependencias en FastAPI.
La documentación oficial de BackgroundTasks de FastAPI, consultada el 22 de julio de 2026, detalla la API y sus límites.