Errori, rate limit e affidabilità
- Leggere la mappa degli errori HTTP e sapere quali status riprovare e quali correggere
- Riprovare gli errori transitori con backoff esponenziale e jitter, con un limite massimo
- Gestire i rate limit con retry-after, smorzamento dei picchi, batching e modelli più economici
- Isolare il tuo codice dalle deprecazioni e migrazioni dei modelli
Il codice in produzione dialoga con un servizio di rete, quindi deve aspettarsi che qualcosa fallisca. Un po' di struttura qui fa la differenza tra un'integrazione instabile e una affidabile.
La mappa degli errori
Gli status HTTP tipici che gestirai:
| Status | Significato | Cosa fare |
|---|---|---|
| 400 | Richiesta non valida | Correggi il payload; non riprovare così com'è |
| 401 | API key errata/mancante | Controlla le credenziali |
| 403 | Non consentito | Controlla accesso/permessi |
| 429 | Rate limit raggiunto | Fai backoff e riprova (rispetta retry-after) |
| 500/529 | Errore del server / sovraccarico | Riprova con backoff |
- Gli SDK li espongono come eccezioni tipizzate, così puoi ramificare in modo pulito anziché analizzare stringhe.
Retry con backoff
Per gli errori transitori (429, 5xx), riprova con backoff esponenziale + jitter, con un limite massimo:
import time, random
for attempt in range(5):
try:
return client.messages.create(...)
except (RateLimitError, APIStatusError) as e:
if attempt == 4 or not should_retry(e):
raise
time.sleep(min(2 ** attempt + random.random(), 30))
- Molti SDK riprovano automaticamente gli errori transitori — conosci il comportamento predefinito del tuo client prima di aggiungere il tuo, altrimenti potresti raddoppiare i retry.
Rate limit
I limiti si applicano per account/tier (richieste e token al minuto). Quando ne raggiungi uno ottieni un 429 con indicazioni temporali. Strategie per restare sotto il tetto:
Guided walkthrough1 of 4
- Quando ricevi un 429, leggi l'indicazione temporale nella risposta e attendi quel tempo prima di riprovare.
- Distribuisci le richieste nel tempo invece di inviarle tutte in una volta.
- Sposta i job ad alto volume e non interattivi nell'elaborazione in batch.
- Indirizza i passi ad alto volume verso un modello più economico — vedi Scegliere un modello.
Vedi Scegliere un modello per scegliere il modello giusto per i passi ad alto volume.
Migrazione dei modelli
Gli ID dei modelli sono datati/versionati e finiscono per essere deprecati. Proteggiti:
- Leggi l'ID del modello dalla configurazione, non da letterali sparsi.
- Tieni d'occhio le deprecazioni — vedi Monitoraggio deprecazioni e migrazioni e la tabella dei modelli.
- Riesegui le tue valutazioni quando cambi modello.
- 400/401/403 sono colpa tua — correggi la richiesta o le credenziali, non riprovare alla cieca. 429 e 500/529 sono riprovabili.
- Riprova gli errori transitori con backoff esponenziale + jitter, con un limite massimo (es. min(2 ** attempt + random(), 30)).
- Su 429: rispetta retry-after, smorza i picchi, raggruppa in batch il lavoro offline e indirizza i passi ad alto volume verso un modello più economico.
- Leggi gli ID dei modelli dalla configurazione, tieni d'occhio le deprecazioni e riesegui le valutazioni quando migri i modelli.