Retry con Requests: Backoff, Session y HTTPAdapter resuelve un problema frecuente en proyectos Python: Repite fallos transitorios con límites sin duplicar operaciones ni provocar una tormenta de peticiones. Esta guía explica el mecanismo, presenta un ejemplo ejecutable y marca los límites que evitan una implementación frágil.
Concepto y caso de uso
Requests no repite conexiones fallidas de forma predeterminada. HTTPAdapter acepta Retry para definir cantidad, estados, métodos y esperas crecientes.
Para repasar los fundamentos relacionados, consulta también la guía de Requests. La integración es más simple cuando cada función recibe dependencias y datos explícitamente en lugar de depender de estado global.
Ejemplo práctico
import requests
from requests.adapters import HTTPAdapter
from urllib3.util import Retry
retry = Retry(
total=4,
backoff_factor=0.5,
status_forcelist=[429, 502, 503, 504],
allowed_methods={"GET", "HEAD"},
respect_retry_after_header=True,
)
session = requests.Session()
session.mount("https://", HTTPAdapter(max_retries=retry))
response = session.get("https://api.example.com/items", timeout=(2, 10))
response.raise_for_status()Restringe retry a operaciones idempotentes, configura timeout en cada intento, respeta Retry-After y añade jitter si muchos clientes repiten juntos.
Decisiones importantes
La elección correcta depende del contrato público, del volumen y del comportamiento ante fallos.
Considera concurrencia, entradas vacías y fallos parciales. Documenta cada límite que afecte a consumidores y usa nombres que expresen intención.
Errores frecuentes
El ejemplo mínimo no sustituye límites, manejo de errores y observabilidad. Repetir POST sin clave de idempotencia puede duplicar cobros o pedidos. Retry ilimitado multiplica latencia y carga durante una caída.
Evita capturar excepciones sin contexto o devolver resultados parciales como si fueran completos. Un fallo explícito suele ser más seguro que datos silenciosamente incorrectos.
Cómo validar
Valida el comportamiento y no solo el camino feliz. Simula 429, 503, timeout y recuperación. Comprueba intentos, duración máxima y fallo rápido para errores permanentes.