Codici di stato HTTP spiegati per sviluppatori — cosa significa ogni codice

Perché devi capire i codici di stato HTTP#

Il tuo sito e-commerce restituisce un errore 500 durante il checkout. I clienti vedono "Qualcosa è andato storto". Ma cosa è andato storto effettivamente? Il server funziona. Il database è su. Il problema è qualcos'altro completamente — ma il 500 non te lo dice.

Il tuo endpoint API restituisce un errore 429 e la tua app mobile crasha invece di mostrare un messaggio di retry. Gli utenti pensano che l'app sia rotta quando in realtà il tuo rate limiter sta facendo il suo lavoro.

La tua pagina di stato dice "All Systems Operational" ma i clienti segnalano pagine che caricano come 403 Forbidden. Il tuo monitoring non l'ha intercettato perché controlla solo la homepage.

I codici di stato HTTP sono segnali. Ti dicono cosa è andato storto e dove guardare. Ma solo se capisci cosa significa ogni codice.

Questa guida spiega ogni codice di stato HTTP che incontrerai, cosa lo innesca e cosa fare quando ne vedi uno.

---

Codici di stato HTTP: il quadro completo#

Le risposte HTTP sono organizzate in cinque classi:

• 1xx (100-199): Informativo — "Richiesta ricevuta, in elaborazione"
• 2xx (200-299): Successo — "Tutto ha funzionato"
• 3xx (300-399): Redirezione — "Prova da un'altra parte"
• 4xx (400-499): Client Error — "Hai fatto un errore tu"
• 5xx (500-599): Server Error — "Abbiamo fatto un errore noi"

Ogni classe ti dice dove sta il problema. Se ricevi errori 4xx, il problema è con la richiesta (URL sbagliato, autenticazione sbagliata, dati mancanti). Se ricevi errori 5xx, il problema è con il tuo server.

---

Codici di stato 2xx Success (Tutto è andato bene)#

200 OK#

Cosa significa: La richiesta è riuscita. Il body della risposta contiene i dati richiesti.

Quando lo vedi:

• Il browser carica una pagina web
• L'API restituisce dati JSON
• L'invio di un form ha successo

Esempio:

GET /api/users/123
Response: 200 OK
Body: {"id": 123, "name": "John", "email": "john@example.com"}

Azione: Nessuna. Tutto sta funzionando correttamente.

201 Created#

Cosa significa: La richiesta è riuscita ed è stata creata una nuova risorsa. La risposta include la risorsa appena creata.

Quando lo vedi:

• POST per creare un nuovo utente restituisce 201 Created
• Creare un nuovo ordine restituisce 201 Created
• Caricare un file restituisce 201 Created

Esempio:

POST /api/users
Request: {"name": "Jane", "email": "jane@example.com"}
Response: 201 Created
Body: {"id": 456, "name": "Jane", "email": "jane@example.com", "created_at": "2026-02-20T10:00:00Z"}

Azione: Nessuna. La risorsa è stata creata con successo.

202 Accepted#

Cosa significa: La richiesta è stata accettata per l'elaborazione, ma non è ancora stata elaborata. Usato per operazioni async.

Quando lo vedi:

• Inviare un job a lunga esecuzione (es. encoding video, generazione report)
• Operazioni di elaborazione batch
• Task che verranno elaborati in background

Esempio:

POST /api/batch-emails/send
Request: {"recipient_ids": [1,2,3,...,10000]}
Response: 202 Accepted
Body: {"job_id": "job_12345", "status": "queued"}

Azione: Il task è in coda. Ricontrolla più tardi usando il job ID per vedere lo stato.

204 No Content#

Cosa significa: La richiesta è riuscita, ma non c'è contenuto da restituire.

Quando lo vedi:

• Richieste DELETE (eliminato con successo, niente da restituire)
• PATCH riuscito senza body di risposta
• Acknowledgment di webhook

Esempio:

DELETE /api/users/123
Response: 204 No Content
Body: (vuoto)

Azione: Nessuna. L'azione è riuscita.

---

Codici di stato 3xx Redirection (Prova da un'altra parte)#

301 Moved Permanently#

Cosa significa: La risorsa è stata spostata permanentemente in un nuovo URL. I motori di ricerca aggiornano il loro indice e i browser usano il nuovo URL per le richieste future.

Quando lo vedi:

• Sito migrato da www.oldsite.com a newsite.com
• Vecchio endpoint API sostituito da uno nuovo
• Struttura URL cambiata

Esempio:

GET /old-page.html
Response: 301 Moved Permanently
Header: Location: /new-page.html

Azione:

• Per gli utenti: il browser segue automaticamente il redirect (trasparente)
• Per la SEO: assicurati che 301 sia usato per modifiche permanenti (Google trasferisce il page rank)
• Per le API: i client dovrebbero aggiornare per usare il nuovo URL

302 Found (Redirect temporaneo)#

Cosa significa: La risorsa è stata spostata temporaneamente in un altro URL. L'URL originale è ancora valido, quindi i browser NON cachano il nuovo URL.

Quando lo vedi:

• Redirect temporanei durante la manutenzione
• Redirect alla pagina di login
• A/B testing (redirige alcuni utenti alla nuova versione temporaneamente)

Esempio:

GET /products/discount-flash-sale
Response: 302 Found
Header: Location: /products/2026-flash-sale

Azione: Il browser segue temporaneamente il redirect, ma tratta ancora l'URL originale come primario.

304 Not Modified#

Cosa significa: La risorsa non è cambiata dalla tua ultima richiesta. Usa la versione cachata.

Quando lo vedi:

• Il browser controlla se la pagina web è cambiata dall'ultima visita (controlla data di modifica/ETag)
• L'API restituisce 304 se i dati non sono cambiati dall'ultima richiesta
• Riduce la banda evitando di re-inviare dati invariati

Esempio:

GET /api/user-profile
Request Header: If-Modified-Since: 2026-02-19 10:00:00
Response: 304 Not Modified
Body: (vuoto — usa la versione cachata da prima)

Azione: Il browser/client usa la versione cachata localmente.

307 Temporary Redirect#

Cosa significa: Come 302, ma garantisce che il metodo HTTP rimanga lo stesso durante il redirect.

Differenza tecnica:

• 302 consente il cambio di metodo (POST → GET dopo redirect)
• 307 preserva il metodo (POST → POST dopo redirect)

Quando lo vedi:

• L'invio di un form redirige alla pagina di conferma (POST → POST)
• Redirect API che devono preservare il metodo

Perché è importante: I browser più vecchi a volte convertivano i redirect POST in GET, il che poteva perdere dati del form. 307 lo previene.

---

Codici 4xx Client Error (Hai fatto un errore tu)#

400 Bad Request#

Cosa significa: La richiesta era malformata. Il server non è riuscito a capirla.

Quando lo vedi:

• JSON malformato nel body della richiesta
• Campi obbligatori mancanti
• Formato parametro non valido
• Errore di sintassi nella query string

Esempio:

POST /api/users
Request Body: {"name": "Jane" "email": "jane@example.com"}
                              ↑ Virgola mancante
Response: 400 Bad Request
Body: {"error": "Invalid JSON syntax"}

Azione:

• Controlla la formattazione della richiesta
• Valida la sintassi JSON
• Assicurati che i campi obbligatori siano presenti
• Verifica che i tipi dei parametri corrispondano alla documentazione API

401 Unauthorized#

Cosa significa: L'autenticazione è fallita o manca. Non hai dimostrato chi sei.

Quando lo vedi:

• Nessun token di autenticazione fornito
• Token di autenticazione non valido o scaduto
• Username/password sbagliati
• Chiave API mancante

Esempio:

GET /api/user-profile
(Nessun header Authorization)
Response: 401 Unauthorized
Body: {"error": "Authentication required"}

Azione:

• Fornisci autenticazione valida (login, chiave API, token, ecc.)
• Aggiorna i token scaduti
• Controlla che le credenziali siano corrette

403 Forbidden#

Cosa significa: L'autenticazione è riuscita, ma non hai il permesso di accedere a questa risorsa.

Quando lo vedi:

• L'utente prova a eliminare l'account di un altro utente
• L'utente prova ad accedere a un endpoint solo admin
• L'utente prova ad accedere a una risorsa di un'altra organizzazione
• Permessi/ruolo insufficienti

Esempio:

DELETE /api/users/999
(Autenticato come utente 123, prova a eliminare l'utente 999)
Response: 403 Forbidden
Body: {"error": "You can only delete your own account"}

Azione:

• Usa l'account corretto con i permessi appropriati
• Richiedi permessi elevati se necessario
• Verifica di accedere alla risorsa giusta

404 Not Found#

Cosa significa: La risorsa non esiste o il server non sa come gestire questo endpoint.

Quando lo vedi:

• Errore di battitura nell'URL (/users/ vs /users)
• L'endpoint non esiste
• Risorsa eliminata
• Versione API sbagliata

Esempio:

GET /api/users/nonexistent-id-12345
Response: 404 Not Found
Body: {"error": "User not found"}

Azione:

• Controlla l'ortografia dell'URL
• Verifica che l'endpoint esista
• Controlla la documentazione API
• Prova un ID/risorsa diversa

405 Method Not Allowed#

Cosa significa: L'endpoint esiste, ma non supporta questo metodo HTTP.

Quando lo vedi:

• Usare POST su un endpoint che accetta solo GET
• Usare DELETE su un endpoint che non supporta l'eliminazione
• Usare PATCH quando è consentito solo PUT

Esempio:

DELETE /api/domains/123
(Se DELETE non è supportato sull'endpoint domains)
Response: 405 Method Not Allowed
Header: Allow: GET, POST, PUT

Azione: Usa il metodo HTTP corretto. La risposta di solito include l'header Allow che mostra i metodi validi.

408 Request Timeout#

Cosa significa: Il server ha aspettato troppo a lungo che il client inviasse la richiesta e ha rinunciato.

Quando lo vedi:

• Client lento che carica un file grande
• La connessione di rete cade a metà richiesta
• La richiesta impiega più del timeout del server (di solito 30-300 secondi)

Esempio:

POST /api/upload
(Caricare un file da 500MB su connessione lenta richiede 10 minuti)
Response: 408 Request Timeout

Azione:

• Riprova la richiesta
• Suddividi richieste grandi in chunk più piccoli
• Controlla la connessione di rete
• Aumenta il timeout del client se appropriato

429 Too Many Requests#

Cosa significa: Stai facendo troppe richieste. Limite di rate superato.

Quando lo vedi:

• Raggiungere il rate limit dell'API (es. 100 richieste/minuto)
• Inviare email troppo velocemente
• Tentativi di login brute force
• Web scraper che colpisce il server troppo duramente

Esempio:

GET /api/users/123
(100esima richiesta nell'ultimo minuto)
Response: 429 Too Many Requests
Header: Retry-After: 60
Body: {"error": "Rate limit exceeded. Try again in 60 seconds"}

Azione:

• Aspetta prima di riprovare (controlla l'header Retry-After)
• Implementa backoff esponenziale
• Usa la paginazione per set di risultati grandi
• Cacha i risultati localmente invece di ri-richiederli

---

Codici 5xx Server Error (Abbiamo fatto un errore noi)#

500 Internal Server Error#

Cosa significa: Qualcosa è andato storto sul server e il server non può fornire più dettagli.

Quando lo vedi:

• Eccezione non gestita nel codice
• Connessione al database fallita
• Memoria esaurita
• Condizione inaspettata

Esempio:

POST /api/checkout
Response: 500 Internal Server Error
Body: {"error": "Something went wrong"}

Perché è vago: I server non espongono dettagli di errore interni ai client per ragioni di sicurezza. Errori dettagliati aiutano gli aggressori.

Azione:

• Controlla i log del server per l'errore effettivo
• Se è un servizio di terze parti: contatta il supporto
• Se è il tuo servizio: controlla i log degli errori, riavvia se necessario, fai rollback del deploy recente

501 Not Implemented#

Cosa significa: Il server non supporta questo metodo HTTP o funzionalità.

Quando lo vedi:

• Il server non supporta funzionalità HTTP/2
• WebSocket non supportato
• Certi metodi HTTP non implementati

Esempio:

OPTIONS /api/users
(Il server non supporta il metodo OPTIONS)
Response: 501 Not Implemented

Azione: Di solito niente — usa un metodo o servizio diverso. Raro nelle API moderne.

502 Bad Gateway#

Cosa significa: Il server ha ricevuto una risposta non valida da un server upstream.

Scenari reali:

1. Reverse proxy (Nginx) non riesce a connettersi al backend

   Client → Nginx (gateway) → Backend Node.js
                   ↑
            Backend è giù o non risponde
   

2. Load balancer non raggiunge alcun backend sano

   Client → Load Balancer → Backend Servers
                         ↑
              Tutti i backend giù o lenti
   

3. API Gateway non raggiunge il microservizio

   Client → API Gateway → Auth Service (giù)
                       → User Service
                       → Order Service
   

Perché succede:

• Il server backend è crashato
• Connettività di rete persa
• Il server upstream è lento e va in timeout
• Upstream restituisce risposta malformata

Esempio:

GET /dashboard
Response: 502 Bad Gateway

Dietro le quinte:

Nginx ha ricevuto la richiesta
Ha provato a inoltrare al server Node.js su localhost:3000
Connessione rifiutata (server non in esecuzione)
Nginx ha restituito: 502 Bad Gateway

Azione:

• Controlla se i servizi backend sono in esecuzione: docker ps, pm2 status, stato systemd
• Controlla la connettività di rete al backend
• Controlla i log del backend per crash
• Riavvia il servizio backend se è crashato
• Controlla se il load balancer sta routando correttamente

503 Service Unavailable#

Cosa significa: Il server è temporaneamente incapace di gestire le richieste (manutenzione, sovraccarico, dipendenze giù).

Quando lo vedi:

• Il server si sta riavviando
• Il server è sotto pesante carico (tutte le connessioni in uso)
• Il database è giù o in fase di migrazione
• Una dipendenza di terze parti è giù
• Deploy in corso (il traffico è in pausa)

Esempio:

GET /api/users
Response: 503 Service Unavailable
Header: Retry-After: 600
Body: {"error": "Server is undergoing maintenance. Try again in 10 minutes"}

Perché i server restituiscono 503 durante la manutenzione:

• Dice ai client "questo è temporaneo, riprova più tardi"
• Browser e client sanno di riprovare automaticamente
• I motori di ricerca non penalizzano 503 (a differenza di 500, che sembra un bug)

Azione:

• Aspetta e riprova (controlla l'header Retry-After per quanto)
• Controlla la pagina di stato per finestre di manutenzione
• Se è un servizio interno: aspetta che il deploy finisca, controlla i log

504 Gateway Timeout#

Cosa significa: Il server non ha ricevuto una risposta dal server upstream in tempo.

Quando lo vedi:

• Il server backend è troppo lento
• Latenza di rete troppo alta
• La query del database impiega troppo tempo
• Il server upstream è bloccato

Esempio:

Richiesta backend:
GET /api/heavy-report
Aspetta 30 secondi...
Timeout!
Response: 504 Gateway Timeout

Causa reale:

Client → Nginx (timeout 30s) → Backend Node.js (query 60s)
                             ↑
              Nginx rinuncia dopo 30s
              Il backend sta ancora eseguendo la query

Azione:

• Controlla le performance del backend
• Cerca query del database lente
• Ottimizza il codice
• Aggiungi indici al database
• Aumenta il timeout se l'operazione legittimamente richiede di più
• Suddividi operazioni lunghe in job async

---

Tabella di riferimento codici di stato HTTP#

Codice	Nome	Categoria	Significato
200	OK	Success	Richiesta riuscita
201	Created	Success	Risorsa creata
202	Accepted	Success	Richiesta in coda per elaborazione
204	No Content	Success	Successo, nessun body di risposta
301	Moved Permanently	Redirect	Usa nuovo URL permanentemente
302	Found	Redirect	Temporaneamente a URL diverso
304	Not Modified	Redirect	Usa versione cachata
307	Temp Redirect	Redirect	Preserva il metodo HTTP nel redirect
400	Bad Request	Client Error	Richiesta malformata
401	Unauthorized	Client Error	Autenticazione richiesta
403	Forbidden	Client Error	Accesso negato
404	Not Found	Client Error	La risorsa non esiste
405	Method Not Allowed	Client Error	Metodo HTTP sbagliato
408	Request Timeout	Client Error	La richiesta ha impiegato troppo
429	Too Many Requests	Client Error	Rate limited
500	Internal Server Error	Server Error	Errore generico del server
501	Not Implemented	Server Error	Funzionalità non supportata
502	Bad Gateway	Server Error	Errore del server upstream
503	Service Unavailable	Server Error	Server temporaneamente giù
504	Gateway Timeout	Server Error	Upstream troppo lento

---

Come fare il debug dei problemi con i codici di stato HTTP#

Passaggio 1: identifica il codice di stato#

Nel browser:

1. Apri Developer Tools (F12)
2. Vai al tab Network
3. Guarda la richiesta che è fallita
4. La colonna Status mostra il codice

Nel terminale:

curl -i https://example.com/endpoint
# La prima riga mostra: HTTP/1.1 200 OK

Nell'applicazione:

• Controlla i log degli errori
• Guarda l'oggetto risposta
• La maggior parte dei framework espone il codice di stato

Passaggio 2: capisci cosa significa#

Usa le categorie:

• 2xx? Funziona come previsto
• 3xx? Controlla la destinazione del redirect
• 4xx? Controlla formato della richiesta e permessi
• 5xx? Controlla i log del server e le dipendenze upstream

Passaggio 3: guarda body e header della risposta#

Body della risposta: La maggior parte delle API include dettagli sull'errore:

{
  "error": "User not found",
  "message": "No user with ID 12345",
  "code": "USER_NOT_FOUND"
}

Header della risposta: Quelli importanti:

• Retry-After — Quanto aspettare prima di riprovare (429, 503)
• Allow — Metodi HTTP validi (405)
• Location — Dove redirigere (3xx)
• WWW-Authenticate — Come autenticarsi (401)

Passaggio 4: agisci in base alla classe del codice#

4xx Client Error:

• Hai inviato dati sbagliati? Correggi la richiesta
• C'è un errore di battitura nell'URL? Correggilo
• Non hai il permesso? Richiedi accesso
• L'endpoint è sbagliato? Controlla la documentazione

5xx Server Error:

• Il server è in esecuzione? Controlla l'uptime
• I log mostrano errori? Risolvi l'errore
• L'upstream è giù? Aspetta il recovery
• È stato deployato? Fai rollback se necessario

---

Esempio reale: fare il debug di un 502 Bad Gateway#

Scenario:

GET /api/checkout
Response: 502 Bad Gateway
I clienti non possono completare gli acquisti

Passaggio 1: conferma che sia un 502 ✓ L'header della risposta mostra HTTP/1.1 502 Bad Gateway

Passaggio 2: controlla cosa significa 502 ✓ Il server upstream non sta rispondendo correttamente

Passaggio 3: diagnostica il problema

I servizi backend sono in esecuzione?

docker ps
# Output: checkout-service is not running

✗ Il servizio checkout è crashato

Passaggio 4: trova la causa principale

Controlla i log:

docker logs checkout-service
# Out of memory error!
# Java heap space exhausted

Passaggio 5: risolvi

Aumenta la memoria:

docker-compose up -d --build

Oppure riavvia:

docker restart checkout-service

Passaggio 6: verifica

curl -i https://api.example.com/api/checkout
# HTTP/1.1 200 OK ✓

---

Monitorare i codici di stato in tempo reale#

Perché dovresti monitorarli#

• Rilevare il downtime prima che i clienti lo segnalino
• Intercettare errori 5xx che colpiscono solo certi endpoint
• Tracciare errori 4xx per trovare uso scorretto dell'API
• Monitorare i rate limit 429 per sapere quando scalare

Cosa monitorare#

Critico (chiamare se giù):

• Qualsiasi errore 5xx su endpoint critici (checkout, login, pagamento)

Importante (investigare):

• Picco negli errori 429 (il rate limiting significa che sei vicino alla capacità)
• Aumento di errori 502/504 (degrado upstream)
• Aumento di errori 403/401 (possibile attacco brute force)

Informativo (tracciare i trend):

• Errori 404 (URL sbagliati richiesti?)
• Errori 400 (i client inviano richieste malformate?)

Usare Nova Uptime per monitorare i codici di stato#

Il monitoraggio uptime di Nova Uptime traccia i codici di stato HTTP in tempo reale:

1. I monitor restituiscono 200? Il sito è su ✓
2. I monitor restituiscono 404? URL sbagliato o endpoint eliminato ✗
3. I monitor restituiscono 429? Sei sotto rate limit ⚠️
4. I monitor restituiscono 502/503? Problema backend ✗
5. I monitor restituiscono 504? Timeout, serve ottimizzazione ⚠️

Nova Uptime ti mostra:

• Quali codici di stato vengono restituiti
• Quando hanno iniziato a verificarsi
• Quali endpoint sono colpiti
• Trend nel tempo

---

Codici di stato HTTP e SEO#

I motori di ricerca usano i codici di stato per decidere come indicizzare le pagine:

200 OK: indicizza questa pagina (normale)

301 Moved Permanently: aggiorna l'indice per puntare al nuovo URL

302 Found: mantieni il vecchio URL nell'indice, non seguire il redirect

304 Not Modified: non re-crawlare, l'ultima versione è corrente

401/403: non indicizzare (accesso negato)

404 Not Found: rimuovi dall'indice (la pagina è andata)

410 Gone: rimuovi dall'indice (la pagina è andata, non tornerà)

429/503/504: riprova più tardi (problema temporaneo)

Errori 5xx: possibile problema del sito; Google rallenta il crawling

Importante per la salute del sito:

• Usa 301 per modifiche URL permanenti (preserva il valore SEO)
• Usa 410 per dire esplicitamente a Google che una pagina è andata
• Risolvi rapidamente gli errori 5xx (Google deprioritizza i siti rotti)
• Implementa robots.txt per prevenire 404 su contenuti non indicizzabili

---

Riepilogo: riferimento rapido codici di stato HTTP#

Tutto va bene:

• 200 OK — Successo normale
• 201 Created — Nuova risorsa creata
• 204 No Content — Successo, nessuna risposta necessaria

Redirigi da un'altra parte:

• 301/302 — Segui il redirect al nuovo URL
• 304 — Usa versione cachata

Hai fatto un errore tu:

• 400 Bad Request — Correggi la formattazione della richiesta
• 401 Unauthorized — Fornisci autenticazione
• 403 Forbidden — Non hai il permesso
• 404 Not Found — URL sbagliato
• 429 Too Many Requests — Rallenta, sei sotto rate limit

Abbiamo fatto un errore noi:

• 500 Internal Server Error — Controlla i log del server
• 502 Bad Gateway — Servizio backend è giù
• 503 Service Unavailable — Server temporaneamente giù
• 504 Gateway Timeout — Backend troppo lento

Monitoring con Nova Uptime: Il monitoraggio HTTP di Nova Uptime intercetta questi errori istantaneamente e ti avvisa prima che i clienti se ne accorgano. Monitora endpoint critici, traccia trend dei codici di stato e ricevi avvisi quando gli errori 5xx si impennano.

---

Ultimo aggiornamento: 20 febbraio 2026 Nova Uptime monitora i codici di stato HTTP su 50+ tipi di check e avvisa sugli errori 5xx in tempo reale