Reintentos, retroceso exponencial y disyuntor
En esta página
Reintentos, retroceso exponencial y disyuntor
Los errores transitorios son normales en producción. El SDK de OpenAI gestiona automáticamente dos reintentos, pero para lograr la máxima resiliencia debes implementar tus propias estrategias. La lección anterior te enseñó a reconocer errores reintentables; esta te enseña a reintentar de forma inteligente, sin empeorar la situación que intentas solucionar.
Retroceso exponencial
El principio es sencillo: cada reintento espera más tiempo que el anterior. Esto evita sobrecargar la API cuando está bajo presión. El jitter merece una atención especial, porque su ausencia provoca un modo de fallo clásico: cincuenta instancias de tu servicio reciben un 429 en el mismo segundo, todas esperan exactamente un segundo, luego todas se reinician juntas y vuelven a ser rechazadas en grupo. Al añadir un retraso aleatorio, distribuyes ese reinicio; esa es la remedy para el «thundering herd» (manada atronadora).
import time
import random
from openai import OpenAI, RateLimitError, InternalServerError, APIConnectionError
client = OpenAI()
def call_with_backoff(prompt: str, max_retries: int = 5) -> str:
"""Llamada a la API con retroceso exponencial y jitter."""
for attempt in range(max_retries):
try:
response = client.responses.create(
model="gpt-5.6-terra",
input=prompt
)
return response.output_text
except (RateLimitError, InternalServerError, APIConnectionError) as e:
if attempt == max_retries - 1:
raise # Último intento, propagar el error
# Retroceso exponencial: 1 s, 2 s, 4 s, 8 s, 16 s
base_delay = 2 ** attempt
# Jitter aleatorio para evitar el thundering herd
jitter = random.uniform(0, base_delay * 0.5)
delay = base_delay + jitter
print(f"Intento {attempt + 1}/{max_retries} fallido. "
f"Reintentando en {delay:.1f} s...")
time.sleep(delay)
raise RuntimeError("Nunca debería llegar aquí")
# Uso
result = call_with_backoff("Explica el retroceso exponencial.")
print(result)
Fíjate en el intento final: propagamos el error original en lugar de silenciarlo. Así, quien llama recibe el diagnóstico real (429 o 500) y puede decidir qué hacer con él.
Uso de la biblioteca Tenacity
Escribir este bucle a mano se vuelve rápidamente repetitivo cuando tienes que proteger cinco funciones. Para una gestión de reintentos más avanzada, tenacity es la herramienta de referencia: el decorador declara la política y el cuerpo de la función solo contiene la llamada a la lógica de negocio. Obtienes los mismos ingredientes, pero nombrados y configurables: la lista de excepciones que deben provocar reintento, la espera exponencial limitada a sesenta segundos, la detención tras cinco intentos y el registro automático antes de cada pausa.
# pip install tenacity
from tenacity import (
retry,
stop_after_attempt,
wait_exponential,
retry_if_exception_type,
before_sleep_log,
)
from openai import RateLimitError, InternalServerError, APIConnectionError
import logging
logger = logging.getLogger(__name__)
@retry(
retry=retry_if_exception_type(
(RateLimitError, InternalServerError, APIConnectionError)
),
wait=wait_exponential(multiplier=1, min=1, max=60),
stop=stop_after_attempt(5),
before_sleep=before_sleep_log(logger, logging.WARNING),
)
def resilient_call(prompt: str, model: str = "gpt-5.6-terra") -> str:
"""Llamada a la API con reintento automático mediante tenacity."""
response = client.responses.create(
model=model,
input=prompt
)
return response.output_text
# Uso: los reintentos son transparentes
result = resilient_call("¡Hola!")
print(result)
El patrón del disyuntor (Circuit Breaker)
El reintento resuelve incidentes que duran unos segundos. Se vuelve perjudicial cuando la interrupción dura más: cada petición de usuario consume entonces cinco intentos y treinta segundos de espera antes de fallar, tus hilos se acumulan y es tu propio servicio el que cae. El disyuntor evita que tu aplicación siga llamando a una API que está fallando.
Funciona como un disyuntor eléctrico, con tres estados. Cerrado: todo funciona con normalidad y las llamadas pasan. Abierto: la API se considera caída y las llamadas se bloquean de inmediato, sin ni siquiera intentar la red; el usuario recibe un error en milisegundos en lugar de tras un tiempo de espera agotado. Semiabierto: una vez transcurrido el periodo de descanso, se envía una llamada de prueba para comprobar si la API ha vuelto: si tiene éxito, el circuito se cierra; si falla, se vuelve a abrir para un nuevo ciclo.
import time
from enum import Enum
class CircuitState(Enum):
CLOSED = "closed"
OPEN = "open"
HALF_OPEN = "half_open"
class CircuitBreaker:
"""Disyuntor para llamadas a la API."""
def __init__(self, error_threshold: int = 5, reset_timeout: float = 30.0):
self.threshold = error_threshold
self.reset_timeout = reset_timeout
self.consecutive_errors = 0
self.state = CircuitState.CLOSED
self.last_error_time = 0.0
def can_call(self) -> bool:
"""Comprueba si se permite una llamada."""
if self.state == CircuitState.CLOSED:
return True
if self.state == CircuitState.OPEN:
if time.monotonic() - self.last_error_time > self.reset_timeout:
self.state = CircuitState.HALF_OPEN
return True # Una llamada de prueba
return False
# Semiabierto: solo se permite una llamada
return True
def record_success(self):
"""Registra una llamada exitosa."""
self.consecutive_errors = 0
self.state = CircuitState.CLOSED
def record_error(self):
"""Registra un fallo."""
self.consecutive_errors += 1
self.last_error_time = time.monotonic()
if self.consecutive_errors >= self.threshold:
self.state = CircuitState.OPEN
print(f"Circuito ABIERTO tras {self.threshold} errores consecutivos")
El contador de errores se reinicia a cero en cuanto una llamada tiene éxito: son los fallos consecutivos los que abren el circuito, no un recuento histórico acumulado. La integración del lado del cliente se reduce entonces a tres pasos: pedir permiso, señalar éxito y señalar fallo.
# Integración con el cliente de OpenAI
circuit = CircuitBreaker(error_threshold=3, reset_timeout=30.0)
def call_with_circuit_breaker(prompt: str) -> str:
"""Llamada a la API protegida por un disyuntor."""
if not circuit.can_call():
raise RuntimeError(
f"Circuito abierto — API no disponible. "
f"Reintenta en {circuit.reset_timeout} s"
)
try:
response = client.responses.create(
model="gpt-5.6-terra",
input=prompt
)
circuit.record_success()
return response.output_text
except (RateLimitError, InternalServerError, APIConnectionError) as e:
circuit.record_error()
raise
# Uso
try:
result = call_with_circuit_breaker("¡Hola!")
print(result)
except RuntimeError as e:
print(f"Error: {e}")
Combinación de los tres patrones
En producción, combina el retroceso, el disyuntor y el tiempo de espera. Fíjate en el constructor: el cliente se crea con max_retries=0, lo que desactiva los reintentos internos del SDK. Sin esto, tus tres intentos se multiplicarían por los dos del SDK y esperarías mucho más de lo previsto. El tiempo de espera de treinta segundos limita cada llamada individual, el bucle gestiona los reintentos y el disyuntor supervisa la salud global del servicio.
class APIClient:
"""Cliente de API resiliente que combina todos los patrones."""
def __init__(self):
self.client = OpenAI(timeout=30.0, max_retries=0)
self.circuit = CircuitBreaker(error_threshold=5, reset_timeout=60.0)
def call(self, prompt: str, max_retries: int = 3) -> str:
if not self.circuit.can_call():
raise RuntimeError("Servicio no disponible temporalmente")
for attempt in range(max_retries):
try:
response = self.client.responses.create(
model="gpt-5.6-terra",
input=prompt
)
self.circuit.record_success()
return response.output_text
except (RateLimitError, InternalServerError) as e:
self.circuit.record_error()
if attempt < max_retries - 1:
delay = (2 ** attempt) + random.uniform(0, 1)
time.sleep(delay)
else:
raise
raise RuntimeError("Fallo tras todos los intentos")
# Uso
api = APIClient()
print(api.call("Explica la resiliencia en ingeniería de software."))
Antes de continuar, prueba este cliente simulando una interrupción: corta la red, lanza una docena de llamadas y verifica que las últimas fallan al instante en lugar de esperar. Si no es así, tu umbral es demasiado alto para el volumen que estás procesando.
Puntos clave
- El SDK gestiona 2 reintentos por defecto; ajústalo con
max_retries - El retroceso exponencial con jitter evita el «thundering herd»
- El disyuntor protege tu aplicación de interrupciones prolongadas
- Usa
tenacitypara una gestión declarativa de reintentos en producción - Combina los tres patrones para lograr la máxima resiliencia
- Nunca reintentes errores 400/401/403 (errores de cliente)