Errore 502 Bad Gateway: cosa significa e come risolverlo

L’errore 502 Bad Gateway indica che un server che funge da «gateway» o «proxy» non ha ricevuto una risposta valida da un server a monte. Nella maggior parte dei casi è un problema temporaneo: prova prima le soluzioni rapide per utenti (aggiornare la pagina, pulire la cache, cambiare browser o rete). Se sei proprietario del sito, controlla i log, la configurazione del CDN, del bilanciatore di carico e delle regole del firewall.

Importante: non forzare modifiche complesse lato server se non hai accesso o competenze adeguate — potresti peggiorare la situazione. Segui prima i controlli base.

Che cos’è un errore 502 Bad Gateway

Un errore 502 Bad Gateway è un codice di stato HTTP che indica un problema di comunicazione tra server. In termini semplici: il tuo browser ha contattato un server (spesso un proxy, un bilanciatore di carico o un CDN), ma quel server non ha ricevuto una risposta valida da un altro server che doveva interrogare. Questo non significa necessariamente che il sito sia rotto per sempre: spesso è un intoppo temporaneo tra componenti della catena di rete.

Definizione rapida: Gateway — un server che riceve richieste dal client e le inoltra ad altri server; Bad Gateway — la risposta ricevuta da quel server a monte è mancante, non valida o errata.

Cause comuni

• Problemi temporanei sul server a monte (crash, riavvio, manutenzione).
• Timeout tra proxy/bilanciatori e server applicativi.
• Errori di configurazione del CDN (mappa dei nomi, instradamento, certificati TLS).
• Firewall o regole proxy che bloccano richieste legittime.
• Limiti di connessione o sovraccarico (rate limiting) sul server a monte.
• Risoluzione DNS errata o cache DNS obsoleta.
• Bug nell’applicazione o nel reverse proxy (ad es. Nginx, HAProxy) che restituiscono risposte non valide.

Cosa provare come utente (passaggi rapidi e spiegati)

Segui questi passaggi in ordine: i primi sono veloci e spesso risolvono il problema.

1. Aggiorna la pagina

A volte è davvero solo un glitch momentaneo: premi F5 o il pulsante di aggiornamento del browser.

2. Prova un altro dispositivo o un’altra rete

Collega lo stesso URL da uno smartphone con rete mobile o da un altro Wi‑Fi. Se il sito funziona altrove, il problema potrebbe essere legato alla tua rete o a restrizioni (es. policy aziendali, firewall scolastici).

3. Svuota la cache del browser e i cookie

La cache può contenere risposte o redirect obsoleti. Pulisci la cache del browser seguendo le impostazioni del tuo browser. Procedura generica:

• Apri la cronologia (CTRL+H su Windows) o le impostazioni del browser.
• Cerca “Cancella dati di navigazione” o “Clear browsing data”.
• Seleziona immagini e file memorizzati nella cache e i cookie.
• Conferma e riavvia il browser.

Suggerimento: prova la modalità di navigazione in incognito per escludere estensioni instabili.

4. Prova un browser diverso

Browser obsoleti o estensioni possono interferire. Usa Chrome, Firefox, Edge o Safari aggiornati per verificare se l’errore è specifico del browser.

5. Flush della cache DNS locale

La cache DNS del dispositivo può contenere mapping errati verso server non raggiungibili. Per svuotarla su Windows apri il Prompt dei comandi e digita:

ipconfig /flushdns

Su macOS:

sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

Su Linux (systemd-resolved):

sudo systemd-resolve --flush-caches

Dopo, riavvia il browser e riprova.

6. Riavvia il router/modem

Un semplice riavvio del router può risolvere problemi temporanei di instradamento.

7. Attendi 5–10 minuti

Se il problema è lato server (deploy, riavvio, saturazione), spesso si risolve automaticamente in pochi minuti.

Importante: evita tentativi ripetuti e frequenti di refresh se sospetti un sovraccarico del server; possono peggiorare la situazione.

Cosa verificare se sei proprietario del sito o amministratore

Se gestisci il sito, le indagini devono essere più tecniche. Ecco una check‑list ordinata per priorità.

1. Controlla i log del server

• Nginx/Apache: error log e access log.
• Application log: per eccezioni o timeout.
• Log del bilanciatore/ingress del Kubernetes.

Cerca 502, 504 (Gateway Timeout), errori di connessione a upstream, o stack trace.

2. Verifica lo stato dei servizi a monte

Assicurati che i server applicativi (ad es. backend, API) siano running e rispondano alle richieste direttamente (curl o httpie). Esempio:

curl -I http://127.0.0.1:8000/health

3. Controlla bilanciatori di carico e health checks

Se l’health check fallisce, il bilanciatore potrebbe evitare l’upstream o restituire 502. Verifica intervalli, path e timeout degli health check.

4. Esamina la configurazione del CDN

Config errate nel CDN (origine sbagliata, certificati TLS scaduti, header mancanti) sono causa comune di 502. Disattiva temporaneamente il CDN per testare la connessione diretta all’origine.

5. Controlla firewall e regole WAF

Un WAF o firewall può bloccare richieste tra proxy e server. Rivedi le regole e i log di blocco.

6. Verifica limiti di connessione e risorse

Processi saturi (CPU, memoria), limiti di worker o connessioni massime possono causare rifiuti di connessione. Controlla metriche di utilizzo e scaling.

7. Controlla aggiornamenti o deploy recenti

Un deploy fallito o una modifica di configurazione recente (es. aggiornamento di libreria, cambio di endpoint) può aver introdotto incompatibilità.

8. Timeout e configurazioni proxy

Assicurati che i timeout di Nginx/HAProxy siano maggiori di quelli dell’applicazione e che la dimensione dei buffer sia adeguata.

9. Ripristino rapido

Se il problema è dovuto a una release recente, considera un rollback alla versione precedente mentre indaghi.

Diagnosi rapida: playbook in 6 passaggi

1. Verifica la presenza del problema (curl, browser).
2. Controlla i log del proxy/bilanciatore.
3. Testa la risorsa upstream direttamente.
4. Controlla CDN/WAF/firewall.
5. Ricontrolla metriche e risorse.
6. Rollback o scale up se necessario.

Diagramma decisionale (aiuta a scegliere l’azione successiva)

flowchart TD
  A[Errore 502 riportato?] --> B{Funziona da altro client?}
  B -- Sì --> C[Problema locale: svuota cache, cambia rete]
  B -- No --> D{Sei proprietario del sito?}
  D -- No --> E[Attendi 5-10 minuti o contatta il supporto del sito]
  D -- Sì --> F[Verifica log del reverse proxy]
  F --> G{Upstream risponde?}
  G -- Sì --> H[Controlla timeouts, header, CDN/WAF]
  G -- No --> I[Riavvia servizio upstream o rollback]
  H --> J[Applica fix e monitora]
  I --> J
  E --> J
  C --> J

Checklist per ruoli (controlli rapidi)

Utente finale:

• Aggiorna la pagina.
• Prova un altro browser/incognito.
• Svuota cache e DNS.
• Cambia rete (mobile vs Wi‑Fi).
• Riavvia router se necessario.

Sviluppatore / DevOps:

• Controlla log proxy e applicazione.
• Testa endpoint upstream con curl.
• Verifica health checks del bilanciatore.
• Controlla limiti di connessioni e risorse.
• Esegui rollback se il deploy è sospetto.

Amministratore CDN/Hosting:

• Verifica mapping dell’origine e certificati TLS.
• Controlla le regole WAF e il blocco per geolocalizzazione.
• Valuta disattivazione temporanea del CDN per isolare il problema.

Quando questo approccio fallisce (contro‑esempi)

• Il server a monte ha un bug non evidente che restituisce risposte malformate: i log applicativi saranno la chiave.
• Problemi di rete intermittenti tra data center: i test locali potrebbero non riprodurli.
• Errori dovuti a dipendenze esterne (API di terze parti) che falliscono solo in particolari condizioni.

In questi casi, servono indagini a livello di rete, packet capture e collaborazioni con il provider di hosting o il team del servizio terzo.

Mini‑glossario (una riga ciascuno)

• Gateway: server che inoltra richieste a un altro server.
• Upstream: server a cui si inoltra la richiesta (backend).
• CDN: Content Delivery Network, distribuisce contenuti geograficamente.
• WAF: Web Application Firewall, protegge applicazioni web.
• Health check: controllo periodico dello stato di un servizio.

Domande frequenti

Q: Un errore 502 è lo stesso di 504?
A: No. 502 è Bad Gateway (risposta non valida); 504 è Gateway Timeout (nessuna risposta entro il timeout).

Q: Posso risolvere tutto da utente?
A: Spesso sì, se il problema è locale (cache, DNS, rete). Se il sito è down per problemi server, devi aspettare o contattare il supporto.

Q: Devo contattare l’hosting o il CDN?
A: Se dopo le verifiche tecniche il problema sembra lato infrastruttura o CDN, contatta il supporto con log e timestamp per accelerare la diagnosi.

Conclusione

L’errore 502 Bad Gateway può sembrare ostico, ma nella maggior parte dei casi è temporaneo e risolvibile con controlli rapidi. Per gli amministratori è essenziale avere una sequenza di diagnosi: log, test diretto a upstream, verifica CDN/WAF e controllo delle risorse. Tenere procedure documentate e alerting efficace riduce i tempi di inattività.

Se hai esperienza personale con questo errore, descrivi i sintomi, l’orario e le azioni intraprese nei commenti qui sotto: queste informazioni aiutano chi indaga a isolare la causa più velocemente.

Criteri di accettazione per una risoluzione standard

• L’errore non deve più riprodursi per più di 10 minuti.
• I log del proxy non mostrano più 502 ricorrenti per lo stesso upstream.
• Gli health checks sono superati regolarmente dal bilanciatore.

Grazie per la lettura. Se vuoi aggiornamenti tecnici o una checklist scaricabile, fammi sapere quale formato preferisci.