Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Retry, Backoff Esponenziale e Circuit Breaker

Lezione 14 di 22 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Retry, Backoff Esponenziale e Circuit Breaker
  2. Backoff Esponenziale
  3. Utilizzo della Libreria Tenacity
  4. Il Pattern Circuit Breaker
  5. Combinare i Tre Pattern
  6. Punti chiave

Retry, Backoff Esponenziale e Circuit Breaker

Gli errori transitori sono normali in produzione. L’SDK di OpenAI gestisce automaticamente due tentativi, ma per una resilienza massima dovresti implementare le tue strategie. La lezione precedente ti ha insegnato a riconoscere gli errori ritentabili; questa ti insegna a ritentare in modo intelligente, senza peggiorare la situazione che stai cercando di risolvere.

Backoff Esponenziale

Il principio è semplice: ogni nuovo tentativo attende più a lungo del precedente. Questo evita di sovraccaricare l’API quando è sotto pressione. Lo jitter merita un’attenzione particolare perché la sua assenza causa un classico modo di guasto: cinquanta istanze del tuo servizio ricevono un errore 429 nello stesso secondo, aspettano tutte esattamente un secondo, poi si riavviano insieme e vengono nuovamente rifiutate come gruppo. Aggiungendo un ritardo casuale, distribuisci questo riavvio: è il rimedio al problema del 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:
    """Chiamata API con backoff esponenziale 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  # Ultimo tentativo, propaga l'errore

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

            # Jitter casuale per evitare il thundering herd
            jitter = random.uniform(0, base_delay * 0.5)
            delay = base_delay + jitter

            print(f"Tentativo {attempt + 1}/{max_retries} fallito. "
                  f"Nuovo tentativo tra {delay:.1f}s...")
            time.sleep(delay)

    raise RuntimeError("Non dovrebbe mai arrivare qui")

# Utilizzo
result = call_with_backoff("Spiega il backoff esponenziale.")
print(result)

Nota l’ultimo tentativo: propaghiamo l’errore originale invece di inghiottirlo. Il chiamante riceve così la diagnosi reale (429 o 500) e può decidere cosa fare.

Utilizzo della Libreria Tenacity

Scrivere questo ciclo a mano diventa rapidamente ripetitivo non appena devi proteggere cinque funzioni. Per una gestione dei retry più avanzata, tenacity è lo strumento di riferimento: il decoratore dichiara la politica e il corpo della funzione contiene solo la chiamata alla logica di business. Ottieni gli stessi ingredienti, ma nominati e configurabili: l’elenco delle eccezioni da ritentare, l’attesa esponenziale limitata a sessanta secondi, l’arresto dopo cinque tentativi e la registrazione automatica dei log prima di ogni 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:
    """Chiamata API con retry automatico tramite tenacity."""
    response = client.responses.create(
        model=model,
        input=prompt
    )
    return response.output_text

# Utilizzo: i retry sono trasparenti
result = resilient_call("Ciao!")
print(result)

Il Pattern Circuit Breaker

Il retry risolve incidenti della durata di pochi secondi. Diventa dannoso quando l’interruzione dura più a lungo: ogni richiesta dell’utente consuma allora cinque tentativi e trenta secondi di attesa prima di fallire, i thread si accumulano ed è il tuo stesso servizio a crollare. Il circuit breaker impedisce alla tua applicazione di continuare a chiamare un’API che non risponde.

Funziona come un interruttore elettrico, con tre stati. Chiuso (Closed): tutto funziona normalmente e le chiamate passano. Aperto (Open): l’API è considerata giù e le chiamate vengono bloccate immediatamente, senza nemmeno tentare la rete; l’utente riceve un errore in millisecondi invece che dopo un timeout. Semi-aperto (Half-open): una volta trascorso il periodo di riposo, viene inviata una chiamata di test per verificare se l’API è tornata operativa: se ha successo, il circuito si chiude; se fallisce, si riapre per un nuovo ciclo.

import time
from enum import Enum

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

class CircuitBreaker:
    """Circuit breaker per chiamate 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 una chiamata è consentita."""
        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 chiamata di test
            return False

        # Semi-aperto: è consentita una sola chiamata
        return True

    def record_success(self):
        """Registra una chiamata riuscita."""
        self.consecutive_errors = 0
        self.state = CircuitState.CLOSED

    def record_error(self):
        """Registra un fallimento."""
        self.consecutive_errors += 1
        self.last_error_time = time.monotonic()

        if self.consecutive_errors >= self.threshold:
            self.state = CircuitState.OPEN
            print(f"Circuito APERTO dopo {self.threshold} errori consecutivi")

Il contatore degli errori si azzera non appena una chiamata ha successo: sono i fallimenti consecutivi ad aprire il circuito, non un conteggio cumulativo storico. L’integrazione lato client si riduce quindi a tre passaggi: chiedere il permesso, segnalare il successo, segnalare il fallimento.

# Integrazione con il client OpenAI
circuit = CircuitBreaker(error_threshold=3, reset_timeout=30.0)

def call_with_circuit_breaker(prompt: str) -> str:
    """Chiamata API protetta da un circuit breaker."""
    if not circuit.can_call():
        raise RuntimeError(
            f"Circuito aperto — API non disponibile. "
            f"Riprova tra {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

# Utilizzo
try:
    result = call_with_circuit_breaker("Ciao!")
    print(result)
except RuntimeError as e:
    print(f"Errore: {e}")

Combinare i Tre Pattern

In produzione, combina backoff, circuit breaker e timeout. Nota il costruttore: il client viene creato con max_retries=0, il che disabilita i retry interni dell’SDK. Senza questa impostazione, i tuoi tre tentativi si moltiplicherebbero per i due dell’SDK e attenderesti molto più del previsto. Il timeout di trenta secondi limita ogni singola chiamata, il ciclo gestisce i retry e il circuit breaker monitora lo stato di salute generale del servizio.

class APIClient:
    """Client API resiliente che combina tutti i pattern."""

    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("Servizio temporaneamente non disponibile")

        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("Fallito dopo tutti i tentativi")

# Utilizzo
api = APIClient()
print(api.call("Spiega la resilienza nell'ingegneria del software."))

Prima di procedere, testa questo client simulando un’interruzione: stacca la rete, lancia una dozzina di chiamate e verifica che le ultime falliscano istantaneamente invece di attendere. Se non è così, la tua soglia è troppo alta per il volume elaborato.

Punti chiave

  • L’SDK gestisce 2 retry di default: regola con max_retries
  • Il backoff esponenziale con jitter evita il thundering herd
  • Il circuit breaker protegge la tua applicazione da interruzioni prolungate
  • Usa tenacity per una gestione dichiarativa dei retry in produzione
  • Combina tutti e tre i pattern per la massima resilienza
  • Non ritentare mai gli errori 400/401/403 (errori client)