Quando le cose vanno storte
Diagnostica gli errori API come un ingegnere, senza tirare a indovinare
⏱ Stima ~6 min
01 · Leggi
Le API si rompono, i server vanno giù, le key scadono, il rate limit si raggiunge, gli URL contengono errori di battitura.
La differenza tra un principiante e un ingegnere non è se le cose vanno storte — è la velocità con cui le diagnostichi e le risolvi.
Approccio sistematico:
1. Leggi il status code — che categoria di errore è? 2. Leggi il corpo della risposta — il server di solito dice esattamente cosa c'è di sbagliato 3. Guarda gli header — Retry-After, WWW-Authenticate, X-RateLimit-* sono miniere d'oro 4. Controlla l'URL — un errore di battitura rompe tutto
Punti chiave
- Per il debug usa sempre curl -i — devi vedere gli header
- Il corpo dell'errore è di solito più utile del status code
- 4xx = problema tuo. 5xx = problema loro.
- Se niente funziona, controlla la pagina di stato del provider API
02 · Esempio di codice
Lista di diagnostica per categoria di status code.
4xx — Errore del client (hai sbagliato tu)
400 Bad Request
→ Check: Is your JSON valid? Are required fields present?
→ Fix: Validate your -d body. Check the API docs for required fields.
401 Unauthorized
→ Check: Did you include the Authorization header? Is the key correct?
→ Fix: Check your API key. Make sure you're using the right header format.
403 Forbidden
→ Check: Do you have permission? Is this feature on your plan?
→ Fix: Check your account permissions or upgrade your plan.
404 Not Found
→ Check: Does the URL path exist? Did you replace all {placeholders}?
→ Fix: Double-check the URL against the docs. Check the resource ID.
429 Too Many Requests
→ Check: Look for Retry-After header — it tells you when to retry.
→ Fix: Slow down. Implement exponential backoff. Use caching.
5xx — Errore del server (problema loro)
500 Internal Server Error
→ Their code crashed. Check their status page.
→ Retry after a brief wait.
503 Service Unavailable
→ Server is overloaded or in maintenance.
→ Check their status page. Wait and retry.
504 Gateway Timeout
→ Your request took too long. The server gave up.
→ Try again. If persistent, contact the API provider.
Errori curl (non hai ancora ricevuto nessuna risposta)
curl: (6) Could not resolve host
→ DNS failure. Check the hostname for typos.
→ Verify your internet connection.
curl: (7) Failed to connect
→ Server unreachable or port blocked.
→ Check if the service is down.
curl: (35) SSL certificate problem
→ Certificate expired or invalid.
→ Check if you're using https:// correctly.
03 · Pratica reale
Fai una richiesta a un repo GitHub che non esiste per scatenare un vero 404.
curl -i https://api.github.com/repos/this-user-doesnt-exist-xyz/no-such-repo
04 · Pratica reale
Fai una richiesta non autenticata a un endpoint che richiede autenticazione per scatenare un vero 401.
curl -i https://api.github.com/user
05 · Quiz
Chiami un'API e ricevi un status code 429. Cosa dovresti fare?
- Controlla la tua API key
- Cambia URL
- Passa a una richiesta POST
- Aspetta un po' e riprova — hai superato il rate limit
06 · Completa
I status code che iniziano con 4 indicano che l'errore è dal lato _____ (la tua richiesta è sbagliata).
Altre lezioni di questo capitolo
⚠ L'esperienza interattiva completa richiede JavaScript. Attivalo e ricarica la pagina.
※ Questo è un progetto educativo indipendente — non è un prodotto ufficiale di Anthropic. Claude™ è un marchio di Anthropic, PBC.