Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Gestione degli errori e codici HTTP

Lezione 12 di 22 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Gestione degli errori e codici HTTP
  2. Codici HTTP dell’API OpenAI
  3. Gestore degli errori completo
  4. Errori specifici dell’API Responses
  5. Registrazione strutturata degli errori
  6. Tabella riassuntiva
  7. Punti chiave

Aggiornato il 3 novembre 2026 in base alla documentazione OpenAI: temperature e top_p sono accettati solo con uno sforzo di ragionamento (reasoning effort) impostato su none, mentre i modelli GPT-5.6 ragionano per impostazione predefinita (medium). Le chiamate che impostano questi parametri devono quindi specificare reasoning={"effort": "none"} (API Responses) o reasoning_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 utilizza gpt-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.

CodiceEccezioneRiprovare?Azione
400BadRequestErrorNoCorreggi la richiesta
401AuthenticationErrorNoVerifica la chiave API
403PermissionDeniedErrorNoVerifica i permessi
404NotFoundErrorNoVerifica modello/endpoint
422UnprocessableEntityErrorNoCorreggi il formato
429RateLimitErrorSìBackoff esponenziale
500InternalServerErrorSìAttendi e riprova
503InternalServerErrorSì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_retries se necessario