Ir al contenido principal
Español— Elegir un idioma
Menú

Reintentos, retroceso exponencial y disyuntor

Lección 14 de 22 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. Reintentos, retroceso exponencial y disyuntor
  2. Retroceso exponencial
  3. Uso de la biblioteca Tenacity
  4. El patrón del disyuntor (Circuit Breaker)
  5. Combinación de los tres patrones
  6. Puntos clave

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 tenacity para 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)