Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Retry, Backoff Exponencial e Disjuntor

Aula 14 de 22 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Retry, Backoff Exponencial e Disjuntor
  2. Backoff Exponencial
  3. Utilização da Biblioteca Tenacity
  4. O Padrão Disjuntor (Circuit Breaker)
  5. Combinação dos Três Padrões
  6. Pontos-chave

Retry, Backoff Exponencial e Disjuntor

Erros transitórios são normais em produção. O SDK da OpenAI gere automaticamente duas tentativas de repetição, mas para obter a máxima resiliência, deve implementar as suas próprias estratégias. A lição anterior ensinou-o a reconhecer erros repetíveis; esta ensina-o a repetir de forma inteligente — sem agravar a situação que tenta resolver.

Backoff Exponencial

O princípio é simples: cada nova tentativa espera mais tempo do que a anterior. Isto impede a sobrecarga da API quando esta está sob pressão. O «jitter» merece atenção especial, pois a sua ausência provoca um modo de falha clássico: cinquenta instâncias do seu serviço recebem um erro 429 no mesmo segundo, esperam todas exatamente um segundo, reiniciam em conjunto e são novamente rejeitadas em bloco. Ao adicionar um atraso aleatório, distribui esse reinício — essa é a cura para o «thundering herd».

import time
import random
from openai import OpenAI, RateLimitError, InternalServerError, APIConnectionError

client = OpenAI()

def call_with_backoff(prompt: str, max_retries: int = 5) -> str:
    """Chamada à API com backoff exponencial e 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  # Última tentativa, propaga o erro

            # Backoff exponencial: 1s, 2s, 4s, 8s, 16s
            base_delay = 2 ** attempt

            # Jitter aleatório para evitar thundering herd
            jitter = random.uniform(0, base_delay * 0.5)
            delay = base_delay + jitter

            print(f"Tentativa {attempt + 1}/{max_retries} falhou. "
                  f"A tentar novamente em {delay:.1f}s...")
            time.sleep(delay)

    raise RuntimeError("Nunca deve chegar aqui")

# Utilização
result = call_with_backoff("Explique o backoff exponencial.")
print(result)

Repare na tentativa final: propagamos o erro original em vez de o suprimir. Assim, o chamador recebe o diagnóstico real — 429 ou 500 — e pode decidir o que fazer com ele.

Utilização da Biblioteca Tenacity

Escrever este ciclo manualmente torna-se rapidamente repetitivo assim que tem cinco funções para proteger. Para uma gestão de repetições mais avançada, a tenacity é a ferramenta de eleição: o decorador declara a política e o corpo da função contém apenas a chamada à lógica de negócio. Obtém os mesmos ingredientes, mas nomeados e configuráveis — a lista de exceções para repetir, a espera exponencial limitada a sessenta segundos, a paragem após cinco tentativas e o registo 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:
    """Chamada à API com repetição automática via tenacity."""
    response = client.responses.create(
        model=model,
        input=prompt
    )
    return response.output_text

# Utilização — as repetições são transparentes
result = resilient_call("Olá!")
print(result)

O Padrão Disjuntor (Circuit Breaker)

O retry resolve incidentes que duram alguns segundos. Torna-se prejudicial quando a indisponibilidade se prolonga: cada pedido do utilizador consome então cinco tentativas e trinta segundos de espera antes de falhar, as suas threads acumulam-se e é o seu próprio serviço que cai. O disjuntor impede que a sua aplicação continue a chamar uma API em falha.

Funciona como um disjuntor elétrico, com três estados. Fechado, tudo funciona normalmente e as chamadas passam. Aberto, a API é considerada indisponível e as chamadas são bloqueadas imediatamente, sem sequer tentar a rede — o utilizador recebe um erro em milissegundos em vez de após um tempo limite. Semi-aberto, assim que o período de descanso termina, é enviada uma chamada de teste para verificar se a API recuperou: se tiver sucesso, o circuito fecha-se; se falhar, reabre para um novo ciclo.

import time
from enum import Enum

class CircuitState(Enum):
    CLOSED = "closed"
    OPEN = "open"
    HALF_OPEN = "half_open"

class CircuitBreaker:
    """Disjuntor para chamadas à 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:
        """Verifica se uma chamada é permitida."""
        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  # Uma chamada de teste
            return False

        # Semi-aberto: apenas uma chamada permitida
        return True

    def record_success(self):
        """Regista uma chamada bem-sucedida."""
        self.consecutive_errors = 0
        self.state = CircuitState.CLOSED

    def record_error(self):
        """Regista uma falha."""
        self.consecutive_errors += 1
        self.last_error_time = time.monotonic()

        if self.consecutive_errors >= self.threshold:
            self.state = CircuitState.OPEN
            print(f"Circuito ABERTO após {self.threshold} erros consecutivos")

O contador de erros repõe-se a zero assim que uma chamada tem sucesso: são os falhos consecutivos que abrem o circuito, não uma contagem cumulativa histórica. A integração do lado do cliente resume-se então a três passos — pedir permissão, sinalizar sucesso, sinalizar falha.

# Integração com o cliente OpenAI
circuit = CircuitBreaker(error_threshold=3, reset_timeout=30.0)

def call_with_circuit_breaker(prompt: str) -> str:
    """Chamada à API protegida por um disjuntor."""
    if not circuit.can_call():
        raise RuntimeError(
            f"Circuito aberto — API indisponível. "
            f"Tente novamente em {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

# Utilização
try:
    result = call_with_circuit_breaker("Olá!")
    print(result)
except RuntimeError as e:
    print(f"Erro: {e}")

Combinação dos Três Padrões

Em produção, combine backoff, disjuntor e tempo limite. Repare no construtor: o cliente é criado com max_retries=0, o que desativa as repetições internas do SDK. Sem isto, as suas três tentativas multiplicar-se-iam pelas duas do SDK e esperaria muito mais tempo do que o previsto. O tempo limite de trinta segundos limita cada chamada individual, o ciclo gere as repetições e o disjuntor monitoriza a saúde global do serviço.

class APIClient:
    """Cliente API resiliente que combina todos os padrões."""

    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("Serviço temporariamente indisponível")

        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("Falha após todas as tentativas")

# Utilização
api = APIClient()
print(api.call("Explique a resiliência na engenharia de software."))

Antes de avançar, teste este cliente simulando uma indisponibilidade: corte a rede, lance uma dúzia de chamadas e verifique se as últimas falham instantaneamente em vez de esperar. Se não for esse o caso, o seu limiar é demasiado alto para o volume processado.

Pontos-chave

  • O SDK gere 2 repetições por padrão — ajuste com max_retries
  • O backoff exponencial com jitter evita o «thundering herd»
  • O disjuntor protege a sua aplicação de indisponibilidades prolongadas
  • Utilize a tenacity para uma gestão declarativa de repetições em produção
  • Combine os três padrões para obter a máxima resiliência
  • Nunca repita erros 400/401/403 (erros do cliente)