Retry, Exponential Backoff en Circuit Breaker
Op deze pagina
Retry, Exponential Backoff en Circuit Breaker
Tijdelijke fouten zijn normaal in productieomgevingen. De OpenAI SDK voert standaard twee retry-pogingen uit, maar voor maximale veerkracht moet u uw eigen strategieën implementeren. In de vorige les leerde u herkenbare retry-fouten identificeren; in deze les leert u intelligent opnieuw proberen—zonder de situatie die u probeert op te lossen te verergeren.
Exponential Backoff
Het principe is eenvoudig: elke retry wacht langer dan de vorige. Dit voorkomt overbelasting van de API wanneer deze onder druk staat. Jitter verdient speciale aandacht, want het ontbreken ervan leidt tot een klassieke faalmodus: vijftig instanties van uw service ontvangen tegelijkertijd een 429-fout, wachten allemaal exact één seconde, starten vervolgens gelijktijdig opnieuw en worden opnieuw als groep geweigerd. Door een willekeurige vertraging toe te voegen, spreidt u deze herstart uit—dat is de remedie tegen de ‘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:
"""API call with exponential backoff and 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 # Last attempt, propagate the error
# Exponential backoff: 1s, 2s, 4s, 8s, 16s
base_delay = 2 ** attempt
# Random jitter to avoid thundering herd
jitter = random.uniform(0, base_delay * 0.5)
delay = base_delay + jitter
print(f"Attempt {attempt + 1}/{max_retries} failed. "
f"Retrying in {delay:.1f}s...")
time.sleep(delay)
raise RuntimeError("Should never reach here")
# Usage
result = call_with_backoff("Explain exponential backoff.")
print(result)
Let op de laatste poging: we geven de oorspronkelijke fout door in plaats van deze te onderdrukken. De aanroeper ontvangt zo de echte diagnose—429 of 500—en kan zelf beslissen wat ermee te doen.
Gebruik van de Tenacity-bibliotheek
Het handmatig schrijven van deze lus wordt snel repetitief zodra u vijf functies moet beschermen. Voor geavanceerder retry-beheer is tenacity het aangewezen instrument: de decorator declareert het beleid, en de functiebody bevat alleen de aanroep van de bedrijfslogica. U krijgt dezelfde ingrediënten, maar dan benoemd en configureerbaar—de lijst met uitzonderingen waarop retry wordt toegepast, exponentieel wachten met een maximum van zestig seconden, stoppen na vijf pogingen, en automatische logging voor elke pauze.
# 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:
"""API call with automatic retry via tenacity."""
response = client.responses.create(
model=model,
input=prompt
)
return response.output_text
# Usage — retries are transparent
result = resilient_call("Hello!")
print(result)
Het Circuit Breaker-patroon
Retry lost incidenten op die enkele seconden duren. Het wordt schadelijk wanneer de uitval langer duurt: elke gebruikersaanvraag verbruikt dan vijf pogingen en dertig seconden wachttijd voordat deze faalt, uw threads stapelen zich op, en uiteindelijk is het uw eigen service die uitvalt. De circuit breaker voorkomt dat uw applicatie een falende API blijft aanroepen.
Het werkt als een elektrische zekering, met drie toestanden. Gesloten (Closed): alles werkt normaal en aanroepen gaan door. Open (Open): de API wordt als niet-beschikbaar beschouwd en aanroepen worden onmiddellijk geblokkeerd, zonder zelfs maar een netwerkpoging—de gebruiker ontvangt binnen milliseconden een fout in plaats van na een timeout. Half-open (Half-open): zodra de rustperiode is verstreken, wordt een testaanroep verzonden om te controleren of de API weer werkt: bij succes sluit het circuit; bij mislukking opent het opnieuw voor een nieuwe cyclus.
import time
from enum import Enum
class CircuitState(Enum):
CLOSED = "closed"
OPEN = "open"
HALF_OPEN = "half_open"
class CircuitBreaker:
"""Circuit breaker for API calls."""
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:
"""Checks if a call is allowed."""
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 # One test call
return False
# Half-open: only one call allowed
return True
def record_success(self):
"""Records a successful call."""
self.consecutive_errors = 0
self.state = CircuitState.CLOSED
def record_error(self):
"""Records a failure."""
self.consecutive_errors += 1
self.last_error_time = time.monotonic()
if self.consecutive_errors >= self.threshold:
self.state = CircuitState.OPEN
print(f"Circuit OPEN after {self.threshold} consecutive errors")
De foutenteller wordt op nul gezet zodra een aanroep slaagt: het zijn opeenvolgende fouten die het circuit openen, niet een historisch cumulatief aantal. Integratie aan de clientzijde komt neer op drie stappen: toestemming vragen, succes melden, fout melden.
# Integration with the OpenAI client
circuit = CircuitBreaker(error_threshold=3, reset_timeout=30.0)
def call_with_circuit_breaker(prompt: str) -> str:
"""API call protected by a circuit breaker."""
if not circuit.can_call():
raise RuntimeError(
f"Circuit open — API unavailable. "
f"Retry in {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
# Usage
try:
result = call_with_circuit_breaker("Hello!")
print(result)
except RuntimeError as e:
print(f"Error: {e}")
Combinatie van de drie patronen
Combineer in productie backoff, circuit breaker en timeout. Let op de constructor: de client wordt gemaakt met max_retries=0, wat de interne retries van de SDK uitschakelt. Zonder dit zouden uw drie pogingen vermenigvuldigd worden met de twee van de SDK, en zou u veel langer wachten dan verwacht. De timeout van dertig seconden begrenst elke individuele aanroep, de lus handelt de retries af, en de circuit breaker bewaakt de algehele gezondheid van de service.
class APIClient:
"""Resilient API client combining all patterns."""
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("Service temporarily unavailable")
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("Failed after all attempts")
# Usage
api = APIClient()
print(api.call("Explain resilience in software engineering."))
Test deze client voordat u verdergaat door een uitval te simuleren: koppel het netwerk af, start een tiental aanroepen en verifieer dat de laatste direct falen in plaats van te wachten. Als dat niet het geval is, is uw drempelwaarde te hoog voor het verwerkte volume.
Belangrijkste punten
- De SDK voert standaard 2 retries uit — pas dit aan met
max_retries - Exponential backoff met jitter voorkomt de ‘thundering herd’
- De circuit breaker beschermt uw applicatie tegen langdurige uitval
- Gebruik
tenacityvoor declaratief retry-beheer in productie - Combineer alle drie de patronen voor maximale veerkracht
- Probeer nooit 400/401/403-fouten opnieuw (clientfouten)