Gestione degli errori e codici HTTP
In questa pagina
Aggiornato il 3 novembre 2026 in base alla documentazione OpenAI:
temperatureetop_psono accettati solo con uno sforzo di ragionamento (reasoning effort) impostato sunone, mentre i modelli GPT-5.6 ragionano per impostazione predefinita (medium). Le chiamate che impostano questi parametri devono quindi specificarereasoning={"effort": "none"}(API Responses) oreasoning_effort="none"(Chat Completions). Fonti: Utilizzo di GPT-6 · GPT-5.6 Terra.
Chiarito il 3 novembre 2026 in base alla pagina Deprecations di OpenAI: l’esempio del modello rimosso utilizzava precedentemente
gpt-4o, che rimane disponibile fino al 14 gennaio 2027; ora utilizzagpt-4-turbo, che è stato dismesso il 23 ottobre 2026 (sostituto indicato:gpt-5.6-sol). Fonte: Deprecations.
Gestione degli errori e codici HTTP
In produzione, gli errori sono inevitabili. La rete cade, una chiave API scade, un collega distribuisce un parametro non valido o l’API stessa subisce un’interruzione di tre minuti. Comprendere i codici HTTP restituiti dall’API e gestirli correttamente è essenziale per costruire applicazioni robuste. L’intera sfida si riduce a una domanda che devi porti per ogni eccezione: questo problema sparirà se riprovo, o entrerò in un loop infinito su un problema che solo un umano può risolvere?
Codici HTTP dell’API OpenAI
L’API restituisce codici HTTP standard per indicare il risultato di ogni richiesta. L’SDK Python non ti permette di gestire manualmente questi codici; invece, traduce ciascuno di essi in un’eccezione tipizzata che puoi intercettare separatamente. Questo ti consente di scrivere blocchi except precisi invece di un generico except Exception che oscurerebbe la natura del problema.
from openai import OpenAI
from openai import (
APIError,
AuthenticationError,
BadRequestError,
RateLimitError,
APIConnectionError,
InternalServerError,
PermissionDeniedError,
NotFoundError,
UnprocessableEntityError,
)
client = OpenAI()
401 — AuthenticationError
Un 401 indica che la chiave API non è valida o manca. In genere vedi questo errore durante il primo deployment quando la variabile d’ambiente non è stata propagata al container. Riprovare è inutile: la chiave sarà altrettanto invalida tra dieci secondi.
try:
# Chiave API non valida o mancante
bad_client = OpenAI(api_key="sk-invalid")
bad_client.responses.create(
model="gpt-5.6-terra",
input="Test"
)
except AuthenticationError as e:
print(f"Code: {e.status_code}") # 401
print(f"Message: {e.message}")
# Azione: verifica la chiave API, rigenerala se necessario
400 — BadRequestError
Un 400 ti dice che la richiesta è malformata. Qui viene fornita una temperatura di 5.0 quando il valore massimo accettato è 2.0. Il messaggio di errore nomina quasi sempre il parametro difettoso, rendendo questo l’errore più veloce da correggere, a patto che tu lo registri correttamente invece di inghiottirlo in silenzio.
try:
# Parametri non validi
client.responses.create(
model="gpt-5.6-terra",
reasoning={"effort": "none"}, # temperature richiede effort none
input="Test",
temperature=5.0 # Valore non valido (max 2.0)
)
except BadRequestError as e:
print(f"Code: {e.status_code}") # 400
print(f"Message: {e.message}")
# Azione: correggi i parametri della richiesta
429 — RateLimitError
Un 429 indica che stai inviando troppe richieste o hai superato la tua quota. A differenza dei due precedenti, questo errore è temporaneo per natura: il contatore si resetta. Questo è il caso da manuale per un retry, ma un retry che attende, e attende più a lungo a ogni tentativo.
try:
# Troppe richieste o quota superata
client.responses.create(
model="gpt-5.6-terra",
input="Test"
)
except RateLimitError as e:
print(f"Code: {e.status_code}") # 429
print(f"Message: {e.message}")
# Azione: attendi e riprova con backoff esponenziale
500/503 — InternalServerError
Gli errori 500 e 503 provengono da OpenAI, non da te. La tua richiesta era valida; l’infrastruttura semplicemente non è riuscita a elaborarla. Riprova dopo un ritardo: nella stragrande maggioranza dei casi, il secondo o il terzo tentativo hanno successo.
try:
client.responses.create(
model="gpt-5.6-terra",
input="Test"
)
except InternalServerError as e:
print(f"Code: {e.status_code}") # 500 o 503
print(f"Message: {e.message}")
# Azione: riprova dopo un ritardo; l'errore è lato OpenAI
Gestore degli errori completo
Mettiamo insieme questi comportamenti in un’unica funzione. La logica è un triage: gli errori fatali vengono convertiti in RuntimeError e sollevati immediatamente, gli errori transitori attivano un’attesa che raddoppia a ogni turno, e se il budget di tentativi è esaurito, la chiamata fallisce in modo pulito invece di restituire un valore vuoto che il chiamante potrebbe interpretare male.
from openai import OpenAI, APIError, AuthenticationError, RateLimitError
from openai import BadRequestError, APIConnectionError, InternalServerError
import time
client = OpenAI()
def robust_api_call(prompt: str, model: str = "gpt-5.6-terra",
max_retries: int = 3) -> str:
"""Chiamata API con gestione completa degli errori."""
for attempt in range(max_retries):
try:
response = client.responses.create(
model=model,
input=prompt
)
return response.output_text
except AuthenticationError:
# Non riprovare — la chiave non è valida
raise RuntimeError("Chiave API non valida. Controlla OPENAI_API_KEY.")
except BadRequestError as e:
# Non riprovare — la richiesta è malformata
raise RuntimeError(f"Richiesta non valida: {e.message}")
except RateLimitError:
# Riprova con backoff esponenziale
delay = 2 ** attempt
print(f"Limite di velocità raggiunto. Attesa di {delay}s...")
time.sleep(delay)
except InternalServerError:
# Riprova — errore lato server
delay = 2 ** attempt
print(f"Errore server. Tentativo {attempt + 1}/{max_retries}...")
time.sleep(delay)
except APIConnectionError:
# Riprova — problema di rete
delay = 2 ** attempt
print(f"Errore di connessione. Tentativo {attempt + 1}/{max_retries}...")
time.sleep(delay)
raise RuntimeError(f"Fallito dopo {max_retries} tentativi")
# Utilizzo
try:
result = robust_api_call("Ciao!")
print(result)
except RuntimeError as e:
print(f"Errore fatale: {e}")
Errori specifici dell’API Responses
Due situazioni meritano un trattamento separato perché appaiono sotto un codice generico ma richiedono una correzione molto specifica.
Contesto troppo lungo
Un prompt che supera la finestra di contesto restituisce un 400, proprio come un errore di battitura in un parametro. Per distinguere tra i due, ispeziona il messaggio: la presenza di context_length_exceeded ti indirizza verso il troncamento del testo o il passaggio a un modello con una finestra di contesto più ampia, piuttosto che alla revisione dei tuoi parametri.
try:
response = client.responses.create(
model="gpt-5.6-terra",
input="x " * 300000 # Supera la finestra di contesto
)
except BadRequestError as e:
if "context_length_exceeded" in str(e.message):
print("Il prompt è troppo lungo per questo modello.")
print("Soluzioni: tronca il testo o passa a un modello")
print("con una finestra di contesto più ampia.")
Modello non disponibile
Gli identificatori dei modelli non sono eterni. Un deployment che fa ancora riferimento a un modello ritirato fallisce con un 404, facendo crashare l’intera applicazione anche se funzionava il giorno prima. Gestisci questo caso esplicitamente: è un promemoria automatico per aggiornare la tua configurazione.
try:
response = client.responses.create(
model="gpt-4-turbo", # rimosso dall'API il 23 ottobre 2026
input="Test"
)
except NotFoundError as e:
print(f"Modello non trovato: {e.message}")
print("Usa gpt-5.6-sol, il sostituto indicato da OpenAI, o un modello più recente.")
Registrazione strutturata degli errori
Un errore non registrato è un errore che scoprirai tramite un ticket del cliente. Registrare in JSON invece che in testo libero cambia tutto quando devi aggregare: puoi contare i 429 all’ora, filtrare per response_id o tracciare la deriva dei consumi, cosa impossibile con righe di log scritte a mano.
import logging
import json
from datetime import datetime
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("openai_client")
def call_with_log(prompt: str) -> str:
"""Chiamata API con registrazione strutturata."""
request_id = None
try:
response = client.responses.create(
model="gpt-5.6-terra",
input=prompt
)
logger.info(json.dumps({
"event": "api_success",
"model": response.model,
"tokens": response.usage.total_tokens,
"response_id": response.id,
"timestamp": datetime.now().isoformat()
}))
return response.output_text
except APIError as e:
logger.error(json.dumps({
"event": "api_error",
"status_code": e.status_code,
"message": e.message,
"timestamp": datetime.now().isoformat()
}))
raise
result = call_with_log("Ciao!")
Tabella riassuntiva
Tieni a portata di mano questa griglia: riassume la decisione da prendere per ogni codice.
| Codice | Eccezione | Riprovare? | Azione |
|---|---|---|---|
| 400 | BadRequestError | No | Correggi la richiesta |
| 401 | AuthenticationError | No | Verifica la chiave API |
| 403 | PermissionDeniedError | No | Verifica i permessi |
| 404 | NotFoundError | No | Verifica modello/endpoint |
| 422 | UnprocessableEntityError | No | Correggi il formato |
| 429 | RateLimitError | Sì | Backoff esponenziale |
| 500 | InternalServerError | Sì | Attendi e riprova |
| 503 | InternalServerError | Sì | Servizio temporaneamente non disponibile |
Punti chiave
- Categorizza gli errori: ripetibili (429, 500, 503) vs fatali (400, 401, 403)
- Usa il backoff esponenziale per gli errori ripetibili
- Non riprovare mai su errori di autenticazione o richieste non valide
- Registra ogni errore con il contesto (codice, messaggio, timestamp)
- L’SDK gestisce automaticamente 2 retry — configura
max_retriesse necessario