Errori, rate limit e affidabilità
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.)
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: rispetta retry-after, smorza i picchi, raggruppa in batch il lavoro offline e usa un modello più economico (Scegliere un modello) 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.