0Pricing
AI Engineering Academy · Lezione

Gestione degli errori e limiti di frequenza

Gestirà gli errori API più comuni, incluse le eccezioni dovute ai rate limit, gli errori di autenticazione e i timeout, usando logiche di retry e pattern di exponential backoff.

Gestione degli errori e limiti di frequenza è una lezione AI Engineering Academy gratuita su CoddyKit. Questa è la lezione 4 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento AI Engineering Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso AI Engineering Academy include 4 lezioni in totale.

Perché si verificano gli errori dell'API

Durante una chiamata API possono verificarsi molti problemi: sovraccarico, quota insufficiente, interruzione della rete o richiesta non valida. Trattare le chiamate come infallibili garantisce la creazione di codice fragile: impari prima a conoscere i tipi di errore.

Panoramica dei tipi di errore di OpenAI

SDK solleva eccezioni specifiche come RateLimitError e AuthenticationError. Vale la pena ritentare solo gli errori temporanei, come i limiti di frequenza e le interruzioni di rete; gli altri non si risolveranno da soli.

Catturare gli errori con Try-Except

Racchiuda ogni chiamata in try-except e catturi eccezioni specifiche, non un except generico. In questo modo può reagire in modo appropriato a ogni errore invece di nascondere i bug. Il codice mostra come fare.

import openai

client = openai.OpenAI()

try:
    response = client.chat.completions.create(
        model='gpt-4o-mini',
        messages=[{'role': 'user', 'content': 'Hello!'}]
    )
    print(response.choices[0].message.content)
except openai.AuthenticationError as e:
    print('Bad API key. Check OPENAI_API_KEY environment variable.')
    raise  # do not retry
except openai.RateLimitError as e:
    print('Rate limited. Back off and retry.')
except openai.APIConnectionError as e:
    print('Network error:', e)
except openai.APIStatusError as e:
    print('Server error', e.status_code, e.message)

Capire i limiti di frequenza

OpenAI applica contemporaneamente due limiti di frequenza: richieste al minuto (RPM) e token al minuto (TPM). Un singolo prompt molto lungo può esaurire la quota TPM con una sola richiesta. Entrambi restituiscono un 429.

Exponential backoff: la strategia corretta per i nuovi tentativi

Ha raggiunto un limite di frequenza? Attenda, poi ritenti usando l'exponential backoff: 1 s, 2 s, 4 s, raddoppiando ogni volta. Aggiunga un po' di jitter e un numero massimo di tentativi, così il ciclo non sarà mai infinito. Veda il codice.

import time
import random
import openai

client = openai.OpenAI()

def call_with_backoff(messages, max_retries=5):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model='gpt-4o-mini',
                messages=messages
            )
        except openai.RateLimitError:
            if attempt == max_retries - 1:
                raise
            wait = (2 ** attempt) + random.uniform(0, 1)
            print(f'Rate limited. Waiting {wait:.1f}s (attempt {attempt+1})')
            time.sleep(wait)
        except (openai.APIConnectionError, openai.APIStatusError):
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)

Usare la libreria tenacity

Non implementi manualmente i nuovi tentativi: la libreria tenacity lo fa in modo pulito. Decori la funzione con @retry e la libreria gestirà per Lei il backoff, il jitter e le condizioni per i nuovi tentativi.

from tenacity import retry, wait_random_exponential, stop_after_attempt
import openai

client = openai.OpenAI()

@retry(
    wait=wait_random_exponential(min=1, max=60),
    stop=stop_after_attempt(6)
)
def completion_with_backoff(**kwargs):
    return client.chat.completions.create(**kwargs)

response = completion_with_backoff(
    model='gpt-4o-mini',
    messages=[{'role': 'user', 'content': 'Tell me a joke.'}]
)
print(response.choices[0].message.content)

Configurare il timeout

Una richiesta bloccata può congelare l'app per sempre, quindi imposti sempre un timeout. SDK accetta un timeout in secondi, sul client o per ogni chiamata. Lo scelga in base alla lunghezza prevista della risposta.

import openai

# Set a default timeout for all requests from this client
client = openai.OpenAI(timeout=30.0)

# Or override per request
try:
    response = client.chat.completions.create(
        model='gpt-4o-mini',
        messages=[{'role': 'user', 'content': 'Summarize the French Revolution.'}],
        timeout=60.0
    )
except openai.APITimeoutError:
    print('Request timed out. Try a shorter prompt or increase timeout.')

Gestire gli errori di autenticazione

Un AuthenticationError (401) significa che la chiave è errata, scaduta o revocata: ritentare non serve. Lo registri, generi un avviso e interrompa subito l'esecuzione invece di consumare il budget dei nuovi tentativi.

import os
import openai

api_key = os.environ.get('OPENAI_API_KEY')
if not api_key:
    raise EnvironmentError(
        'OPENAI_API_KEY not set. Export it before running.'
    )

client = openai.OpenAI(api_key=api_key)

try:
    response = client.chat.completions.create(
        model='gpt-4o-mini',
        messages=[{'role': 'user', 'content': 'Hello'}]
    )
except openai.AuthenticationError:
    # Do NOT retry - the key itself is invalid
    raise RuntimeError('Invalid API key. Check OPENAI_API_KEY.')

Quota e limiti di frequenza a confronto

Entrambi possono sembrare un RateLimitError, ma sono diversi: i limiti di frequenza sono restrizioni al minuto che si azzerano automaticamente, mentre i limiti di quota sono massimali di spesa che richiedono ulteriori crediti.

Registrare gli errori per il debug

In produzione, registri ogni errore insieme al contesto: tipo, modello, parametri, conteggio dei token, ora e ID della richiesta. Proprio quell'ID è ciò che serve al supporto OpenAI. Veda il codice.

import logging
import openai

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

client = openai.OpenAI()

def safe_completion(model, messages):
    try:
        response = client.chat.completions.create(
            model=model, messages=messages
        )
        return response
    except openai.RateLimitError as e:
        logger.warning(
            'Rate limit hit',
            extra={'model': model, 'error': str(e)}
        )
        raise
    except openai.APIStatusError as e:
        logger.error(
            'API server error',
            extra={
                'status_code': e.status_code,
                'request_id': e.request_id,
                'model': model
            }
        )
        raise

Gestire gli errori nelle app di produzione

Una solida strategia per la produzione prevede di interrompere subito l'esecuzione in caso di errori non recuperabili, ritentare quelli temporanei con backoff e fornire fallback appropriati. Non permetta mai che un singolo errore dell'API mandi in crash l'intero server.

Verifica rapida

Verifichi la Sua comprensione dei concetti di AI Engineering trattati in questa lezione.

Riepilogo della lezione

Ha imparato a gestire gli errori: OpenAI solleva eccezioni specifiche, i limiti di frequenza richiedono backoff con jitter e gli errori di autenticazione devono interrompere subito l'esecuzione. Prossimo argomento: scrivere prompt efficaci.

Domande Frequenti

La lezione «Gestione degli errori e limiti di frequenza» è gratuita?

Sì — il testo completo di «Gestione degli errori e limiti di frequenza» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso AI Engineering Academy, passa a CoddyKit PRO. Il corso AI Engineering Academy include 4 lezioni in totale.

Cosa imparerò in «Gestione degli errori e limiti di frequenza»?

Gestirà gli errori API più comuni, incluse le eccezioni dovute ai rate limit, gli errori di autenticazione e i timeout, usando logiche di retry e pattern di exponential backoff. Eserciti AI Engineering Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare AI Engineering Academy?

Non è richiesta alcuna esperienza precedente. AI Engineering Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 4 di 4.

Quanto tempo richiede la lezione «Gestione degli errori e limiti di frequenza»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione AI Engineering Academy?

Sì. Ogni lezione AI Engineering Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

  1. Configurare l'ambiente Python
  2. L'endpoint Chat Completions
  3. Controllare il comportamento del modello con i parametri
  4. Gestione degli errori e limiti di frequenza
← Torna a AI Engineering Academy