Errori 502, 503 e 504: cosa significa effettivamente ciascuno di essi

502, 503 e 504 significano tutti più o meno “il server non può darti una risposta reale in questo momento”, motivo per cui sono così spesso confusi l’uno con l’altro. Ma ogni codice restringe il problema in modo diverso e la lettura corretta del numero consente di risparmiare tempo nella risoluzione dei problemi del livello sbagliato.

La distinzione rapida

• 502 Bad Gateway: un server che funge da gateway o proxy ha ricevuto una risposta non valida dal server dietro di esso.
• 503 Servizio non disponibile: il server è attivo ma si rifiuta deliberatamente di gestire la richiesta in questo momento (sovraccarico o in manutenzione).
• 504 Gateway Timeout: un server che funge da gateway o proxy non ha ricevuto nessuna risposta dal server dietro di esso entro il limite di tempo.

Lo schema: 502 e 504 coinvolgono entrambi due server: un proxy/bilanciatore del carico/CDN davanti e un server delle applicazioni dietro di esso. 503 di solito è solo un server che ti dice direttamente che non è pronto.

502 Gateway difettoso

Cosa sta succedendo: Un proxy inverso, un bilanciatore del carico o un CDN (come Cloudflare o Nginx che funge da gateway) ha inoltrato la tua richiesta al server dell’applicazione effettivo e ha ricevuto una risposta che non è riuscito a comprendere o che non era corretta, non silenzio, una risposta effettivamente interrotta.

Cause comuni:

• Il server delle applicazioni (nodo, PHP-FPM, un processo di backend) si è bloccato o è stato riavviato durante la richiesta.
• Un proxy inverso configurato in modo errato che punta alla porta o all’indirizzo sbagliato.
• Il backend ha restituito una risposta che viola la formattazione HTTP di base.
• Un CDN o un WAF davanti al sito non è configurato correttamente e rifiuta una risposta di backend legittima.

Cosa controllare se si tratta del tuo sito: Controlla i log del server delle applicazioni per individuare eventuali arresti anomali o riavvii nel momento in cui si verifica l’errore. Conferma che la configurazione del proxy inverso (nginx proxy_pass, destinazione del bilanciatore del carico e così via) punti a un backend effettivamente in esecuzione sulla porta prevista.

503 Servizio non disponibile

Che cosa sta succedendo: Il server ha ricevuto correttamente la tua richiesta, ma ti sta dicendo esplicitamente che non può gestirla al momento. A differenza del 502/504, questo è solitamente intenzionale: un server dichiara la propria condizione piuttosto che un proxy che si lamenta di cosa c’è dietro.

Cause comuni:

• Manutenzione pianificata: molte piattaforme restituiscono 503 di proposito durante la distribuzione o l’aggiornamento, spesso con un’intestazione Retry-After.
• Sovraccarico: troppe richieste simultanee per la capacità del server, comune durante i picchi di traffico (una vendita, un post virale, un DDoS).
• Esaurimento risorse: il server ha esaurito la memoria, le connessioni al database o i processi di lavoro per gestire le nuove richieste.
• Limitazione della velocità: alcune configurazioni restituiscono 503 anziché 429 quando un client (o un servizio upstream) invia le richieste troppo velocemente.

Cosa controllare se si tratta del tuo sito: Se questo problema è apparso durante una distribuzione, potrebbe risolversi da solo in pochi secondi o minuti. Se il problema persiste, controlla l’utilizzo delle risorse del server (CPU, memoria, limiti del pool di connessioni) e i registri del gestore del processo per verificare se i lavoratori non riescono ad avviarsi o vengono uccisi.

504 Timeout del gateway

Che cosa succede: Stessa configurazione a due server del 502, ma invece di ricevere una risposta interrotta dal backend, il proxy non ha ottenuto nulla entro il tempo di attesa assegnato. È il fratello “gateway” di un semplice timeout di connessione.

Cause comuni:

• Il backend impiega troppo tempo per elaborare la richiesta: una query di database lenta, uno script non ottimizzato o una dipendenza (API, servizio di terze parti) che è di per sé lenta o inattiva.
• Il backend è sovraccarico e troppo occupato per rispondere in tempo, anche se non si è bloccato.
• Un’impostazione di timeout proxy troppo aggressiva per un’operazione legittimamente lenta (ma funzionante), come il caricamento di file di grandi dimensioni o la generazione di report pesanti.

Cosa controllare se si tratta del tuo sito: Profila direttamente l’endpoint lento, ignorando il proxy, per vedere se il backend stesso è lento o se il problema è puramente a livello del proxy. Controlla se una dipendenza specifica (database, API esterna) è danneggiata, poiché questa è la causa principale più comune del rallentamento del backend anziché del crash totale.

Sei tu o sono loro?

Tutti e tre questi sono errori lato server per definizione: non sono causati dal tuo browser, dal tuo DNS o dalla tua rete locale, il che li distingue chiaramente da problemi come ERR_CONNECTION_TIMED_OUT o DNS_PROBE_FINISHED_NXDOMAIN. Se vedi un 502, 503 o 504, la correzione (se ce n’è una che puoi fare) non è quasi mai da parte tua: l’aggiornamento occasionalmente funziona per un 503 temporaneo, ma uno persistente significa semplicemente aspettare che il sito lo risolva.

Per confermare che non sei solo tu (alcuni CDN o nodi edge regionali occasionalmente segnalano un errore di gateway errato mentre altri vanno bene) esegui il sito attraverso un controllo dello stato indipendente per vedere il codice di stato HTTP in tempo reale da un server esterno alla tua rete, insieme al tempo di risposta e allo stato SSL nella stessa visualizzazione.