Un errore 503 Service Unavailable significa che il web server ha ricevuto la richiesta ma in questo momento non può gestirla. Il server è raggiungibile, quindi DNS e rete funzionano, ma l’applicazione alle sue spalle è sovraccarica, in manutenzione o non riesce a raggiungere un servizio da cui dipende. Un 503 dovrebbe essere temporaneo. Se dura più di qualche minuto, c’è qualcosa da sistemare: di solito troppo traffico, troppo pochi worker, un processo applicativo fermo o un backend non disponibile.
Questa guida spiega cosa provoca un 503, come trovarne la causa sul tuo server, come risolvere ciascuna causa e come assicurarti di venire a sapere del prossimo prima dei tuoi clienti.
Cosa ti dice davvero un errore 503
I codici di stato HTTP della serie 5xx indicano un errore del server, non del visitatore. All’interno di questa famiglia, il 503 ha un significato preciso: il servizio al momento non è disponibile e il client può riprovare più tardi. Confrontalo con i codici vicini:
500 Internal Server Error: l’applicazione si è bloccata mentre gestiva la richiesta.
502 Bad Gateway: un proxy o un load balancer ha ricevuto una risposta non valida dal server alle sue spalle.
503 Service Unavailable: il server, o qualcosa davanti a esso, si rifiuta di elaborare la richiesta perché è sovraccarico, in manutenzione o non ha nulla di funzionante a cui inoltrarla.
504 Gateway Timeout: un proxy ha aspettato il server alle sue spalle e alla fine ha rinunciato.
La distinzione è importante perché ti indica dove guardare. Un 503 raramente è un bug in una singola pagina. Quasi sempre riguarda la capacità o la disponibilità di un intero servizio. Per una panoramica completa dei codici e di quali un monitor dovrebbe considerare come down, leggi il nostro prontuario dei codici di stato HTTP per il monitoraggio.
Cause comuni di un errore 503
Picchi di traffico e sovraccarico
Ogni server può gestire un numero limitato di richieste contemporaneamente. Un’email di una campagna, una menzione sui social o un bot che scansiona migliaia di pagine possono spingerlo oltre quel limite. Quando la coda è piena, il web server o l’applicazione inizia a rifiutare le nuove richieste con un 503. Spesso il sito torna a funzionare qualche minuto dopo, per poi fallire di nuovo al picco successivo.
Manutenzione programmata
Molti sistemi restituiscono un 503 di proposito durante la manutenzione. WordPress lo fa mentre installa gli aggiornamenti: scrive un file .maintenance e mostra una breve pagina “Briefly unavailable for scheduled maintenance” con stato 503. Se un aggiornamento si interrompe, quel file può rimanere al suo posto e il sito continua a restituire 503 finché qualcuno non lo elimina.
Processo applicativo o application pool fermo
Sui server Windows con IIS, un application pool fermo o bloccato produce il classico “HTTP Error 503. The service is unavailable.” Il pool può fermarsi per crash ripetuti, una password dell’identità errata o una modifica alla configurazione. Su Linux, l’equivalente è un processo Node, Python o Java terminato, che lascia il reverse proxy senza nulla a cui inoltrare le richieste.
PHP-FPM senza worker liberi
I siti PHP dietro nginx o Apache di solito usano PHP-FPM con un numero fisso di processi worker, impostato da pm.max_children. Quando tutti i worker sono occupati, per esempio perché ogni richiesta attende una query lenta sul database o un’API esterna, le nuove richieste finiscono in coda. A seconda della configurazione, il visitatore riceve un 503, un 502 o un 504. Il log di PHP-FPM ti dice se sta succedendo:
WARNING: [pool www] server reached pm.max_children setting (10), consider raising it
Rate limiting
I limiti di frequenza proteggono un server dagli abusi, ma se sono troppo stretti restituiscono errori anche agli utenti reali. nginx restituisce 503 per impostazione predefinita quando una richiesta supera una zona limit_req. I web application firewall e alcune piattaforme di hosting fanno lo stesso. Se un ufficio, un client API o un servizio di monitoraggio condivide un indirizzo IP con molti utenti, possono raggiungere il limite tutti insieme.
Upstream o backend non disponibile
Load balancer e reverse proxy restituiscono 503 quando non hanno un server funzionante a cui inviare il traffico. Se gli health check segnano tutti i backend come non funzionanti, dopo un deploy difettoso o perché il database è fermo e l’endpoint di health check lo segnala, il proxy risponde 503 a ogni richiesta.
Problemi della CDN e dell’origine
Se il tuo sito è dietro una CDN, il 503 potrebbe arrivare dalla CDN e non dal tuo server. La CDN può restituirlo quando la tua origine è sovraccarica o irraggiungibile, oppure quando la CDN stessa ha problemi in una regione. Gli header della risposta di solito ti dicono chi ha risposto: cerca l’header server o l’ID richiesta della CDN e confronta con una richiesta inviata direttamente all’origine.
Come trovare la causa
Parti dalla risposta stessa. Richiedi l’URL che fallisce e guarda gli header:
curl -sS -o /dev/null -D – https://northwind.shop/checkout
L’header Server e gli eventuali header specifici della CDN mostrano quale livello ha risposto. Un header Retry-After fa pensare a una manutenzione intenzionale. Poi procedi verso l’interno:
Verifica se succede ovunque. Fallisce anche la homepage o solo un percorso? Un singolo percorso indica una route dell’applicazione o un pool di worker; se fallisce tutto, il problema è nel server o nel proxy.
Leggi il log degli errori del web server. nginx e Apache registrano con timestamp gli errori dell’upstream, le richieste respinte dal rate limiting e gli errori di connessione.
Leggi il log dell’applicazione o di PHP-FPM. Cerca avvisi max_children, crash, processi terminati per memoria esaurita e trace delle richieste lente.
Controlla le risorse del server. CPU, carico, memoria e swap nel momento dell’errore. Un server che va in swap risponde lentamente, e le risposte lente riempiono i pool di worker.
Controlla le dipendenze. Il database risponde? La cache è attiva? Un’API esterna che chiami in modo sincrono risponde lentamente?
Controlla le modifiche recenti. Un deploy, l’aggiornamento di un plugin, una modifica alla configurazione o un nuovo rate limit nel periodo in cui sono iniziati gli errori sono la causa più probabile.
Come risolvere un errore 503
La soluzione dipende dalla causa. Ecco le più comuni, nell’ordine in cui la maggior parte dei team le incontra.
Modalità manutenzione bloccata: elimina il file .maintenance nella root di WordPress o disattiva il flag di manutenzione del tuo framework, poi completa o riprova l’aggiornamento.
Sovraccarico da traffico reale: metti in cache tutto il possibile sull’edge e nell’applicazione, così la maggior parte delle richieste non arriva mai a PHP o al database. Poi aggiungi capacità: più worker se la memoria lo consente, un server più grande o più server dietro il load balancer.
Sovraccarico da bot: individua gli user agent e gli intervalli IP nel tuo access log e limitali o bloccali sulla CDN o sul firewall, prima che arrivino all’applicazione.
Worker PHP-FPM: alza pm.max_children solo fin dove la memoria lo consente. Calcola la memoria media di un worker e dividi per questo valore la memoria che puoi liberare. Se i worker sono occupati per colpa di query lente, correggi prima le query, altrimenti sposti soltanto il collo di bottiglia.
Application pool o processo fermo: riavvialo, poi scopri perché si è fermato. Cerca i crash nel registro eventi o nel journal di sistema e configura un process manager che riavvii il servizio in automatico.
Rate limit troppo restrittivi: alza il limite o la dimensione del burst, escludi indirizzi IP noti come quello del tuo ufficio o del tuo servizio di monitoraggio e restituisci 429 invece di 503 ai client limitati, così la causa è evidente nei log.
Backend non funzionanti: controlla cosa richiede l’health check del load balancer e perché fallisce. Prima annulla un deploy difettoso, poi indaga.
Ecco una tipica modifica al pool di PHP-FPM per un server con spazio per altri worker. I numeri sono un esempio, non una raccomandazione per il tuo server:
; /etc/php/8.2/fpm/pool.d/www.conf
pm = dynamic
pm.max_children = 24
pm.start_servers = 6
pm.min_spare_servers = 4
pm.max_spare_servers = 10
request_slowlog_timeout = 5s
slowlog = /var/log/php-fpm/www-slow.log
La parte utile è lo slow log: mostra quali script tengono occupati i worker più a lungo, ed è lì che devi guardare dopo.
Usa Retry-After durante la manutenzione programmata
Quando metti offline un sito di proposito, restituisci un 503 con un header Retry-After. Comunica a browser, client API e crawler dei motori di ricerca che l’interruzione è temporanea e quando tornare. Il valore è un numero di secondi oppure una data HTTP:
HTTP/1.1 503 Service Unavailable
Retry-After: 1800
Content-Type: text/html; charset=utf-8
In nginx, un semplice interruttore per la manutenzione può essere così:
if (-f /var/www/maintenance.flag) {
return 503;
}
error_page 503 @maintenance;
location @maintenance {
add_header Retry-After 1800 always;
root /var/www/maintenance;
rewrite ^ /index.html break;
}
Due regole rendono indolore la manutenzione programmata. Restituisci un 503, mai un 200 con una pagina “torniamo presto”, perché un 200 dice a crawler e monitor che la pagina di manutenzione è il tuo vero contenuto. E falla breve: un 503 per un’ora va bene, un 503 per giorni rischia di far sparire le pagine dai risultati di ricerca.
Avvisa anche i clienti in anticipo. Una nota sulla tua pagina di stato risponde a “è un problema solo mio?” prima che qualcuno lo chieda.
Come il monitoraggio intercetta gli errori 503
Un 503 spesso va e viene. Il sito fallisce per due minuti al picco di una campagna, si riprende e fallisce di nuovo un’ora dopo. Nessuno nel team se ne accorge, perché quando qualcuno apre il sito funziona. I clienti però l’hanno visto.
Un monitor HTTP richiede le tue pagine a intervalli regolari e registra il codice di stato e il tempo di risposta di ogni controllo. Un 503 è un controllo fallito. Un buon monitoraggio fa poi tre cose:
Conferma l’errore. Un secondo controllo esclude un’anomalia isolata, e un controllo da un’altra località esclude anche un problema su un singolo percorso di rete. Uptimecheck esegue controlli da Stoccolma, Londra e New York e conferma ogni errore da una seconda località prima di aprire un incidente.
Avvisa le persone giuste. L’avviso contiene il codice di stato, l’URL e l’ora di inizio, così chi lo prende in carico sa che si tratta di un 503 e non di un errore DNS. In Uptimecheck l’incidente include anche la risposta fallita e uno screenshot, così vedi la pagina di errore che hanno visto i tuoi visitatori, oppure un traceroute quando il server non ha risposto affatto. Trovi i canali in avvisi e notifiche.
Registra l’andamento. Lo storico degli incidenti mostra se i 503 si concentrano nei picchi di traffico, durante i deploy o con i job notturni, e ti dice quale soluzione provare per prima.
Non monitorare solo la homepage. La homepage è spesso in cache e continua a funzionare mentre checkout, login o API falliscono. Aggiungi monitor di uptime per le pagine che portano fatturato e tieni d’occhio l’andamento del tempo di risposta: una pagina che rallenta ogni giorno alla stessa ora è spesso un 503 pronto a scattare. La nostra guida su qual è un buon tempo di risposta per un sito web spiega a cosa fare attenzione.
Le metriche del server chiudono il cerchio. Quando arriva un avviso per un 503, la prima domanda è se il server ha esaurito CPU, memoria o disco. Con il monitoraggio dei server accanto ai controlli di uptime, vedi causa e sintomo fianco a fianco.
Checklist per l’errore 503
Guarda gli header della risposta per capire quale livello ha restituito il 503.
Controlla i log del web server, dell’applicazione e di PHP-FPM allo stesso timestamp.
Controlla CPU, memoria, swap e disco sul server.
Cerca deploy, aggiornamenti e modifiche alla configurazione appena prima dell’inizio degli errori.
Risolvi la causa: cache, più worker, un processo riavviato, un rate limit meno severo o un backend funzionante.
Usa un 503 con Retry-After per la manutenzione programmata, mai un 200.
Monitora le pagine chiave ogni minuto e conferma ogni errore con un secondo controllo prima di inviare un avviso.
In sintesi
Un 503 significa che il server c’è ma in questo momento non può servirti. È un problema di capacità o di disponibilità, non una pagina rotta, e i log allo stesso timestamp di solito portano dritti alla causa. Risolvi la causa invece del sintomo, usa Retry-After quando l’interruzione è programmata e lascia che il monitoraggio ti segnali i 503 brevi che altrimenti non vedresti mai.
Uptimecheck monitora siti web, API e server in un unico account e ti avvisa quando una pagina inizia a restituire 503. Inizia la prova gratuita di 14 giorni, senza carta di credito.