0Pricing
AI Agents · Lezione

Gestione delle risposte e degli errori delle API

Parsing delle risposte JSON, codici di errore e pattern di gestione delle eccezioni

Gestione delle risposte e degli errori delle API è una lezione AI Agents gratuita su CoddyKit. Questa è la lezione 3 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 Agents, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso AI Agents include 4 lezioni in totale.

L'oggetto Response

Ogni chiamata di requests restituisce un oggetto Response. Contiene tutto ciò che il server ha restituito: il codice di stato, le intestazioni e il corpo. Prima di elaborare il corpo, verifichi sempre il codice di stato: una risposta con stato 500 contiene comunque un corpo, ma non conterrà i dati desiderati.

import requests

response = requests.get('https://api.example.com/data')

# Key attributes of the response
print(response.status_code)       # e.g. 200
print(response.headers)           # dict of response headers
print(response.headers.get('Content-Type'))  # 'application/json'
print(response.text)              # raw response body as string
print(response.content)           # raw bytes

Analisi del JSON con response.json()

Chiami response.json() per analizzare automaticamente il corpo della risposta come JSON e convertirlo in un dict o una list Python. È equivalente a json.loads(response.text), ma verifica anche che Content-Type sia appropriato.

Chiami .json() solo quando sa che la risposta è effettivamente JSON: verifichi prima l'intestazione Content-Type.

import requests

response = requests.get(
    'https://api.example.com/users/42',
    headers={'Authorization': 'Bearer YOUR_KEY'}
)

# Parse JSON body
user = response.json()

# Access fields safely with .get()
name = user.get('name', 'Unknown')
email = user.get('email', '')
roles = user.get('roles', [])

print(f'User: {name} ({email})')
print(f'Roles: {roles}')

Verifica di status_code prima dell'analisi

Non chiami mai response.json() senza aver prima verificato che la richiesta sia andata a buon fine. Le risposte di errore (4xx/5xx) spesso restituiscono dettagli JSON sugli errori, utili per il debug, ma non sono i dati necessari. Verifichi sempre prima status_code.

import requests

response = requests.post(
    'https://api.example.com/tasks',
    json={'title': 'Write report'},
    headers={'Authorization': 'Bearer YOUR_KEY'}
)

if response.status_code == 201:
    task = response.json()
    print('Task created, ID:', task['id'])
elif response.status_code == 400:
    error = response.json()
    print('Validation error:', error.get('message'))
elif response.status_code == 401:
    print('Auth failed — check your token')
else:
    print(f'Unexpected status {response.status_code}: {response.text[:200]}')

raise_for_status() — Sollevamento automatico degli errori

response.raise_for_status() solleva automaticamente un'eccezione HTTPError se il codice di stato è 4xx o 5xx. È un modo pulito per convertire le risposte HTTP non valide in eccezioni Python, consentendo di usare try/except invece di lunghe catene if/elif.

import requests
from requests.exceptions import HTTPError

try:
    response = requests.get(
        'https://api.example.com/users/9999',
        headers={'Authorization': 'Bearer YOUR_KEY'}
    )
    response.raise_for_status()  # raises if status >= 400
    user = response.json()
    print('Found user:', user['name'])

except HTTPError as e:
    print(f'HTTP error: {e.response.status_code}')
    print('Details:', e.response.text[:300])

Gestione di JSONDecodeError

A volte un'API restituisce una risposta non JSON quando ci si aspetta JSON: una pagina HTML di errore del server, un corpo vuoto o un file binario. Chiamare response.json() su queste risposte solleva json.JSONDecodeError. Intercetti sempre questa eccezione per evitare arresti silenziosi dell'agente.

import requests
import json

response = requests.get(
    'https://api.example.com/report',
    headers={'Authorization': 'Bearer YOUR_KEY'}
)

try:
    data = response.json()
except json.JSONDecodeError as e:
    print(f'Response is not valid JSON: {e}')
    print('Content-Type:', response.headers.get('Content-Type'))
    print('First 200 chars:', response.text[:200])
    # Decide: is this an HTML error page? A CSV file?
    data = None

if data is None:
    print('Falling back to text processing')

ConnectionError — Problemi di rete

Si verifica un ConnectionError quando l'agente non riesce a raggiungere affatto il server: può trattarsi di un errore di risoluzione DNS, di un server offline o di un firewall che blocca la richiesta. È un errore a livello di rete, che si verifica prima ancora di qualsiasi comunicazione HTTP.

A differenza di un errore 5xx, questa non è una risposta del server: la connessione non è mai stata stabilita.

import requests
from requests.exceptions import ConnectionError

try:
    response = requests.get('https://api.example.com/data')
    data = response.json()
except ConnectionError as e:
    print('Cannot reach server. Possible causes:')
    print('- DNS failure (bad hostname)')
    print('- Server is down')
    print('- No internet connection')
    print('- Firewall blocking the port')
    print(f'Error detail: {e}')
    # Consider: queue the request for retry when connectivity returns

Timeout — Impedire che gli agenti si blocchino

Per impostazione predefinita, requests attende indefinitamente una risposta. Un server lento o bloccato può quindi congelare l'agente senza limiti di tempo. Imposti sempre un timeout: una tupla di (connect_timeout, read_timeout) espressa in secondi. Se il server non risponde entro il tempo previsto, viene sollevata un'eccezione Timeout.

import requests
from requests.exceptions import Timeout

try:
    response = requests.get(
        'https://api.example.com/slow-endpoint',
        headers={'Authorization': 'Bearer YOUR_KEY'},
        timeout=(5, 30)  # 5s to connect, 30s to read
    )
    data = response.json()
except Timeout:
    print('Request timed out after 30 seconds')
    print('Options: retry, use cached result, or alert operator')

Gestione completa delle eccezioni

Negli agenti di produzione, gestisca tutte le eccezioni di requests secondo una gerarchia coerente. requests.exceptions.RequestException è la classe base di tutti gli errori di requests: intercettarla offre una rete di sicurezza per i problemi di rete imprevisti.

import requests
import json
from requests.exceptions import (
    ConnectionError, Timeout, HTTPError, RequestException
)

def safe_api_call(url, headers):
    try:
        r = requests.get(url, headers=headers, timeout=(5, 30))
        r.raise_for_status()
        return r.json()
    except Timeout:
        print('ERROR: Request timed out')
    except ConnectionError:
        print('ERROR: Cannot reach server')
    except HTTPError as e:
        print(f'ERROR: HTTP {e.response.status_code}')
        try:
            print('API error:', e.response.json().get('message'))
        except json.JSONDecodeError:
            print('Non-JSON error body')
    except RequestException as e:
        print(f'ERROR: Unexpected request error: {e}')
    return None

Registrazione delle risposte per il debug

Quando un agente si comporta in modo anomalo, è necessario disporre di un contesto sufficiente per diagnosticarlo. Registri il metodo della richiesta, l'URL, il codice di stato e i dettagli rilevanti della risposta, ma non registri mai le chiavi API. Per gli agenti di produzione utilizzi il modulo logging integrato in Python invece delle istruzioni print.

import logging
import requests

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger('agent.api')

def logged_request(method, url, **kwargs):
    logger.info(f'-> {method.upper()} {url}')
    response = requests.request(method, url, **kwargs)
    logger.info(
        f'<- {response.status_code} '
        f'({len(response.content)} bytes) '
        f'{response.elapsed.total_seconds():.2f}s'
    )
    if response.status_code >= 400:
        logger.error(f'Error body: {response.text[:500]}')
    return response

Gestione delle risposte paginate

Molte API restituiscono i dati in pagine. L'agente deve seguire i link di paginazione per ottenere tutti i risultati. Cerchi un URL next nella risposta oppure un campo page/cursor e ripeta il ciclo finché non ci sono più pagine.

import requests

def get_all_items(base_url, headers):
    all_items = []
    url = f'{base_url}/items?page=1&limit=100'

    while url:
        response = requests.get(url, headers=headers)
        response.raise_for_status()
        data = response.json()

        all_items.extend(data.get('items', []))

        # Follow 'next' link if present
        url = data.get('next_page_url')  # None stops the loop

        print(f'Fetched {len(all_items)} items so far...')

    print(f'Total: {len(all_items)} items')
    return all_items

Streaming di risposte di grandi dimensioni

Per le risposte di grandi dimensioni, come file o output lunghi generati dall'IA, utilizzi stream=True per evitare di caricare l'intera risposta in memoria in una sola volta. Legga la risposta in blocchi. È essenziale quando l'agente elabora grandi set di dati o trasmette testo generato dall'IA.

import requests

response = requests.get(
    'https://api.example.com/large-report',
    headers={'Authorization': 'Bearer YOUR_KEY'},
    stream=True
)

response.raise_for_status()

# Write streamed content to file
with open('report.json', 'wb') as f:
    for chunk in response.iter_content(chunk_size=8192):
        if chunk:
            f.write(chunk)

print('Download complete')

# For streaming JSON lines (NDJSON):
for line in response.iter_lines():
    if line:
        import json
        record = json.loads(line)
        print(record)

Verifica rapida: raise_for_status

Verifichi la propria comprensione della gestione degli errori nelle risposte.

Riepilogo della gestione delle risposte

Una gestione robusta delle risposte è ciò che distingue un agente fragile da uno affidabile:

  • Verifichi sempre status_code prima di analizzare il corpo
  • Utilizzi response.json() per l'analisi e intercetti JSONDecodeError se il corpo potrebbe non essere JSON
  • Utilizzi raise_for_status() per convertire gli errori HTTP in eccezioni
  • Intercetti ConnectionError per i problemi di rete e Timeout per i server lenti
  • Imposti sempre una tupla timeout=(connect, read) per ogni richiesta
  • Registri richieste e risposte, senza le chiavi, per facilitare il debug

Domande Frequenti

La lezione «Gestione delle risposte e degli errori delle API» è gratuita?

Sì — il testo completo di «Gestione delle risposte e degli errori delle API» è 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 Agents, passa a CoddyKit PRO. Il corso AI Agents include 4 lezioni in totale.

Cosa imparerò in «Gestione delle risposte e degli errori delle API»?

Parsing delle risposte JSON, codici di errore e pattern di gestione delle eccezioni Eserciti AI Agents 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 Agents?

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

Quanto tempo richiede la lezione «Gestione delle risposte e degli errori delle API»?

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 Agents?

Sì. Ogni lezione AI Agents 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. Fondamenti delle REST API per sviluppatori di agenti
  2. Autenticazione: API key e OAuth
  3. Gestione delle risposte e degli errori delle API
  4. Rate limiting e logica di retry
← Torna a AI Agents