Programma Lezione 121 di 250 · Chiamare un vero LLM
Chiamare un vero LLM

Gestire gli errori dell'API

Le chiamate di rete vere falliscono, e un client LLM di produzione vive o muore per come reagisce. L'istinto più utile in assoluto è dividere i fallimenti in due cesti: quelli che vale la pena riprovare (un intoppo passeggero che probabilmente si risolverà) e quelli che devi correggere nella richiesta (un bug nella tua chiamata che nessun numero di tentativi risolverà). Il codice di stato HTTP ti dice in quale cesto sei.

Nel codice vero catturi le eccezioni tipizzate dell'SDK, che portano ciascuna un .status_code (solo illustrativo -> non chiamiamo la rete):

import anthropic
try:
    resp = client.messages.create(model="claude-opus-5-5", max_tokens=1024,
                                  messages=history)
except anthropic.RateLimitError:          # HTTP 429 -> back off and retry
    ...
except anthropic.APIStatusError as e:     # any other 4xx/5xx, has e.status_code
    if should_retry(e.status_code):
        ...   # retry with backoff
    else:
        raise # 400/401/403/404 -> a bug in YOUR request, surface it

I cesti, per codice di stato:

  • Riprova -> 408 (timeout della richiesta), 409 (conflitto), 429 (limite di frequenza), e qualsiasi errore del server da 500 a 599, come 502, 503 (non disponibile) o 529 (sovraccarico). Sono passeggeri: aspetta, poi riprova. Quando la risposta porta un header retry-after, aspetta almeno quel tempo.
  • Correggi la richiesta -> 400 (richiesta non valida), 401 (chiave API sbagliata), 403 (vietato), 404 (modello o percorso sbagliato). Riprovare una chiamata malformata brucia solo quota.
  • Sconosciuto -> qualsiasi altra cosa (compreso un successo come 200): non dare per scontato che sia sicuro riprovare.

Stai costruendo due piccole funzioni. classify_error(status) restituisce il nome del cesto: "retry", "fix-request" o "unknown". should_retry(status) restituisce il booleano -> True esattamente quando lo stato è nell'insieme da riprovare, altrimenti False.

Questa lezione decide se riprovare; l'attesa tra un tentativo e l'altro è un'abilità a sé. Il modulo production-patterns tratta il backoff esponenziale (raddoppia l'attesa a ogni tentativo: 1s, 2s, 4s ...), e sopra a quello AGGIUNGI il jitter -> una piccola quantità casuale di attesa in più -> così una flotta di client respinti nello stesso istante non riprova tutta allo stesso ritmo travolgendo di nuovo il server (la "mandria tonante", thundering herd). Costruiscilo in modo che la tabella degli stati dia diverse risposte (429 -> retry, 400 -> fix-request, 200 -> unknown), quindi nessuna costante può passare.

Tocca a te

Scrivi classify_error(status) che restituisce "retry" per 408 (timeout della richiesta), 409 (conflitto), 429 (limite di frequenza) e ogni errore del server da 500 a 599 (529 significa sovraccarico), "fix-request" per {400, 401, 403, 404}, e "unknown" per qualsiasi altra cosa. Scrivi should_retry(status) che restituisce il booleano True esattamente quando classify_error(status) è "retry", altrimenti False. (È la stessa regola che usa l'SDK ufficiale di Anthropic: riprova questi stati, e gli errori di connessione, due volte di default, e aspetta quanto chiede un header retry-after. Nel codice vero di solito configuri max_retries invece di scriverlo tu; scriverlo una volta ti mostra che cosa fa.)

Hai notato un problema in questa lezione? Segnalalo · Chiedi qualcosa su questa lezione

Questo esercizio si apre presto

Finisci la lezione precedente e questa si sblocca. L'intero corso è gratuito, senza account, e puoi leggere questa lezione subito.