Errore 504 Gateway Timeout: cause e soluzioni

L’errore 504 Gateway Timeout compare quando un server intermedio aspetta una risposta dal server che deve generare la pagina, e quella risposta non arriva in tempo. Non si tratta di un guasto improvviso ma di un’attesa che ha superato il limite consentito. Per questo il 504 è quasi sempre il sintomo di qualcosa di lento: uno script, una query al database, una chiamata a un servizio esterno che non risponde.

In questa guida vediamo che cosa significa, come distinguerlo dagli errori simili, quali sono le cause più comuni e come risolverlo, con un approfondimento sui casi tipici di WordPress.

Cosa significa errore 504

Il 504 fa parte degli errori 5xx. Come per il 502, il protagonista è un server che fa da intermediario: un CDN, un bilanciatore di carico o il server web che passa le richieste a PHP. Questo server apre la connessione verso il livello successivo, invia la richiesta e si mette in attesa. Ogni server ha però un tempo massimo di attesa: se la risposta non arriva entro quel limite, smette di aspettare e restituisce al browser un 504.

La differenza con il 502 è sottile ma importante. Con il 502 la risposta arriva sbagliata o la connessione fallisce subito; con il 504 la connessione funziona, ma dall’altra parte qualcuno sta impiegando troppo tempo. Capire questa differenza orienta la ricerca: con un 504 non si cerca un servizio spento, si cerca un’operazione lenta.

Come si presenta

I messaggi più frequenti sono 504 Gateway Timeout, Gateway Time-out con la scritta nginx in fondo alla pagina, HTTP Error 504 e The server didn’t respond in time. Sui siti che passano da Cloudflare, una situazione simile può comparire come errore 524, il codice che Cloudflare usa quando il server di origine ha accettato la connessione ma non ha risposto entro il tempo massimo previsto dal CDN.

Un indizio utile è il tempo che passa prima che compaia l’errore. Se la pagina resta in caricamento per trenta, sessanta o cento secondi e solo allora mostra il 504, sei quasi certamente davanti a uno script che lavora troppo a lungo. Se l’errore compare subito, la causa è più probabilmente nella configurazione dei server intermedi.

Le cause più comuni

Script lenti o bloccati

È la causa principale. Un’importazione di prodotti, la generazione di un report, un backup lanciato dal browser, un page builder che salva una pagina molto complessa: operazioni che richiedono più tempo del limite impostato sul server intermedio. Nel log degli errori di Nginx compare una riga come questa:

upstream timed out (110: Connection timed out) while reading response header from upstream

Il messaggio dice che Nginx ha atteso la risposta di PHP o del server di origine fino al limite e poi ha rinunciato.

Query al database pesanti

Un database cresciuto senza manutenzione, tabelle senza indici, plugin che eseguono ricerche complesse a ogni caricamento di pagina: tutte situazioni in cui la pagina aspetta il database per secondi. Quando l’attesa supera il limite, il visitatore vede un 504 anche se il sito, tecnicamente, non è rotto.

Servizi esterni che non rispondono

Molti siti, durante il caricamento, interrogano servizi esterni: API di pagamento, sistemi di spedizione, feed di prodotti, servizi di traduzione o di verifica delle licenze dei plugin. Se uno di questi servizi è lento o irraggiungibile e il codice non ha un timeout breve, la pagina resta in attesa fino a far scattare il 504.

Server sovraccarico

Quando il server è al limite delle risorse, anche le operazioni normali rallentano. Le richieste si accodano, ognuna aspetta il proprio turno e quelle in fondo alla coda superano il tempo massimo. In questi casi il 504 compare soprattutto nelle ore di maggior traffico.

Problemi di rete tra CDN e hosting

Più raramente, la lentezza è nella rete: un collegamento degradato tra il CDN e il server di origine o un firewall che rallenta le connessioni possono allungare i tempi fino a superare il limite.

Come risolvere se sei un visitatore

Ricarica la pagina dopo qualche minuto: se il server era solo momentaneamente sotto carico, la richiesta successiva potrebbe passare. Se stavi inviando un modulo o completando un acquisto, prima di riprovare verifica se l’operazione è andata comunque a buon fine, per esempio controllando l’email di conferma: con il 504 il server potrebbe aver completato il lavoro anche se tu non hai ricevuto la risposta. Se l’errore persiste, il problema è lato server e serve l’intervento del gestore.

Come risolvere se il sito è tuo

1. Individua le pagine coinvolte

Il 504 colpisce tutto il sito o solo alcune pagine? Se riguarda solo l’area amministrativa, un’importazione o una pagina specifica, la causa è in quello che fanno quelle pagine. Se colpisce tutto il sito, guarda alle risorse del server o a un componente caricato ovunque.

2. Leggi i log

Il log del server web conferma se si tratta di un timeout verso PHP o verso il server di origine; il log di PHP e, su WordPress, il file di debug possono indicare quale script stava lavorando. Molti hosting mettono a disposizione anche un log delle query lente del database. Trovi dove cercarli nella guida ai log del server.

3. Sposta le operazioni pesanti fuori dal browser

Importazioni, backup e invii massivi di email non dovrebbero dipendere da una pagina aperta nel browser. Molti plugin permettono di eseguirli a blocchi o in background; su un VPS, gli strumenti da riga di comando come WP-CLI non sono soggetti ai timeout del server web e completano operazioni lunghe senza errori.

4. Ottimizza database e plugin

Pulisci revisioni, transienti scaduti e dati di plugin disinstallati, verifica che le tabelle più usate abbiano gli indici corretti e individua i plugin che eseguono query pesanti. Strumenti di analisi delle prestazioni per WordPress mostrano quali componenti rallentano una pagina e quante query eseguono.

5. Imposta timeout brevi per i servizi esterni

Se il sito dipende da API esterne, assicurati che il codice abbia un tempo di attesa ragionevole e una gestione dell’errore: meglio mostrare un messaggio “servizio momentaneamente non disponibile” in una sezione della pagina che bloccare l’intera pagina per un minuto.

6. Aumenta i limiti solo se necessario

Su un server che gestisci direttamente puoi alzare i tempi massimi di attesa. In Nginx si usano direttive come fastcgi_read_timeout per PHP e proxy_read_timeout quando Nginx fa da proxy verso un’altra applicazione; anche il limite max_execution_time di PHP deve essere coerente:

fastcgi_read_timeout 120s;

Alzare i timeout è però un rimedio, non una cura. Una pagina che impiega due minuti a caricarsi resta un problema anche se non mostra più l’errore: i visitatori se ne vanno molto prima. Su un hosting condiviso questi valori non sono modificabili, e se pensi che siano la causa va contattata l’assistenza.

Errore 504 su WordPress

Su WordPress il 504 compare spesso in tre situazioni. La prima sono le operazioni di massa: aggiornare decine di plugin insieme, importare migliaia di prodotti in WooCommerce, rigenerare le miniature di tutte le immagini. La seconda è WP-Cron, il sistema che esegue le attività programmate durante le visite: se un’attività pesante parte durante una visita, quella visita può andare in timeout. Per questo sui siti con traffico conviene disattivare il cron interno e affidarlo a un cron reale del server. La terza sono i page builder su pagine molto lunghe, che al salvataggio elaborano grandi quantità di dati. Per gli altri problemi tipici della piattaforma, consulta la guida agli errori di WordPress.

504, 502 e 503 a confronto

Il 502 indica una risposta non valida o una connessione fallita tra server intermedio e server di origine, il 504 una risposta arrivata troppo tardi, l’errore 503 un servizio temporaneamente indisponibile per manutenzione o sovraccarico. Nella pratica, quando un server è in difficoltà può mostrare tutti e tre gli errori in momenti diversi: il codice esatto ti dice in quale punto della catena si è inceppato.

Errore 504 e SEO

Google tratta il 504 come qualsiasi errore del server: se è occasionale riprova più tardi, se è frequente riduce la scansione e, nei casi più gravi, rimuove temporaneamente le pagine dai risultati. C’è però un effetto meno visibile: le pagine lente che non arrivano al timeout peggiorano comunque l’esperienza degli utenti e le metriche di velocità. Risolvere la causa di un 504, quindi, migliora il sito ben oltre la scomparsa dell’errore.

Domande frequenti

Quanto aspetta il server prima di dare un 504?

Dipende dalla configurazione. Molti server web hanno limiti predefiniti di circa sessanta secondi, mentre i CDN hanno limiti propri. Su un hosting condiviso il valore è deciso dal provider e di solito non può essere modificato dal cliente, che deve quindi intervenire sulla lentezza dello script.

Se ricevo un 504, l’operazione è stata annullata?

Non necessariamente. Il server intermedio ha smesso di aspettare, ma il server di origine potrebbe aver completato il lavoro. Prima di ripetere un pagamento o un’importazione, verifica se l’operazione risulta già eseguita.

Il 504 può dipendere dal DNS?

Il messaggio DNS lookup timeout che a volte accompagna un 504 indica che un server non è riuscito a risolvere un nome di dominio in tempo. Succede soprattutto quando il sito interroga servizi esterni e i DNS del server rispondono lentamente.