Errore 500, 502, 503: che cosa significa ogni codice

Quando un sito si rompe, il riflesso è aprire il codice. Il codice di errore mostrato è un indizio più rapido: dice quale livello ha ceduto, e i tre più comuni indicano tre riparazioni completamente diverse. Cinque minuti di lettura qui risparmiano un'ora di ricerca nel posto sbagliato.

I tre codici, in una tabella

Il 504 non è nel titolo e accompagna gli altri così spesso da meritare la sua riga: è l'unico dei quattro a indicare lentezza invece che arresto.

500: l'applicazione è andata in crash

Il server è in piedi e ha risposto. È il tuo codice che non è arrivato in fondo.

Le tre cause che tornano più spesso:

• Un errore fatale dopo un deploy: una dipendenza mancante, una versione di linguaggio diversa, un file di configurazione assente.
• Il database non risponde più: servizio fermo, connessioni esaurite, password cambiata e non propagata.
• Il disco è pieno. È la causa più sottovalutata, perché non somiglia a nulla: le sessioni non si scrivono più, i log nemmeno, e l'applicazione inciampa in errori incoerenti.

Dove guardare: il log applicativo, al minuto in cui è comparso l'errore. Un 500 lascia quasi sempre una traccia, con un file e un numero di riga.

502: la macchina davanti ha ricevuto una brutta risposta

Un 502 viene da un proxy: Nginx, un bilanciatore, una CDN. Ha trasmesso la richiesta del tuo visitatore al server dietro e ha ricevuto in cambio qualcosa di inutilizzabile, o niente del tutto.

Le tre cause abituali:

• Il processo dietro è morto o non è mai partito: PHP-FPM fermo, un servizio Node andato in crash, un container che non è ripartito dopo un deploy.
• La via di comunicazione è sbagliata: un socket rinominato, una porta cambiata, un indirizzo interno spostato durante un aggiornamento.
• Il processo è stato ucciso per mancanza di memoria. Il log di sistema lo dice, l'applicazione no.

Dove guardare: lo stato del servizio dietro il proxy, prima del codice. Un 502 è l'unica delle tre risposte che quasi mai nasce dal tuo programma, ed è proprio per questo che viene attribuita male così spesso.

503: il server rifiuta, temporaneamente

Un 503 è una risposta voluta: non adesso. O il sito è in modalità manutenzione, o il server ha esaurito la capacità e rifiuta invece di crollare.

È la più rassicurante delle tre: nulla è rotto. È anche quella che dura più a lungo, perché segue di solito un picco di traffico o una coda che non si svuota. Ed è l'unica che può essere la risposta giusta: durante una manutenzione annunciata, un 503 con un header Retry-After è esattamente ciò che va restituito.

Dove guardare: se è rimasto attivo un flag di manutenzione, poi il carico. Una modalità manutenzione dimenticata dopo un deploy del venerdì è un classico assoluto. Controllala prima di ipotizzare qualsiasi cosa sul carico: costa dieci secondi e spiega buona parte dei 503.

Dove leggere il log, secondo lo stack

tail -n 100 /var/log/nginx/error.log        # Nginx, compresi 502 e 504
tail -n 100 /var/log/apache2/error.log      # Apache
journalctl -u php8.3-fpm --since "10 min ago"   # PHP-FPM, processi morti
tail -n 100 storage/logs/laravel.log        # l'applicazione, per i 500
df -h && free -m                            # disco pieno, memoria esaurita

L'ordine conta: il log del server web dice quale livello ha fallito, il log applicativo dice perché. Cominciare dal secondo quando il guasto è un 502 equivale a cercare un errore in un file che non è mai stato eseguito.

Che cosa verificare presso l'hosting prima di accusare il proprio codice

Tre cose, e richiedono due minuti:

• La pagina di stato dell'hosting. Una manutenzione su un database condiviso produce 500 per tutti nello stesso momento.
• Le quote. Numero di processi, memoria per processo, connessioni simultanee al database: superarle produce esattamente gli stessi sintomi di un bug.
• Un addebito rifiutato. Un servizio sospeso per morosità risponde spesso con un 503, e l'avviso originale è finito nello spam tre settimane fa.

Ricorda soprattutto che nessuno ti avviserà spontaneamente: una pagina di stato verde mentre il tuo sito restituisce 500 è una situazione perfettamente normale dal punto di vista dell'hosting, visto che la sua macchina risponde.

Che cosa dire al cliente nel frattempo

È il paragrafo che nessuno scrive e che tutti cercano. Bastano due righe, e non citano alcun codice:

Il sito mostra un errore dalle 14:20. Abbiamo individuato da dove arriva e ci stiamo lavorando. Le do notizie alle 15.

Non dire «errore 502», nessuno sa che cosa sia e dà l'impressione che tu stia recitando. Non promettere un orario di ripristino finché la causa è sconosciuta. E avvisa prima che te lo chiedano: un cliente che scopre il guasto da solo ricorda l'incidente, un cliente avvisato ricorda la risposta.

I tre errori di diagnosi che costano più tempo

Riavviare prima di leggere. Un riavvio cancella di solito la traccia di ciò che si è rotto: il processo morto riparte, il log ricomincia, e il guasto torna due ore dopo senza che tu ne sappia di più. Prima leggere, poi riavviare, in quest'ordine, per quanto forte sia la tentazione.

Credere che il codice indichi il colpevole. Indica il livello che ha segnalato il problema, non quello che lo ha causato. Un 502 restituito da Nginx è quasi sempre un problema PHP, e un 500 applicativo è a volte un disco pieno, quindi un problema di sistema.

Trattare un incidente isolato come una tendenza. Un singolo 502 alle tre del mattino, durante una rotazione dei log, non richiede alcuna azione. Tre 502 nella stessa giornata sì. La differenza è visibile solo se qualcosa conserva lo storico, ed è questo il vero apporto di un monitoraggio rispetto alla lettura occasionale di un log.

Che cosa questi codici non dicono

Non dicono se il visitatore ha visto la pagina. Un utente il cui browser l'aveva in cache non si è accorto di nulla; un altro, arrivato nello stesso momento da un risultato di ricerca, ha visto l'errore a tutto schermo. Non dicono nemmeno quante persone sono coinvolte: un errore che tocca una sola rotta, un modulo d'ordine per esempio, può restituire un numero ridicolo di 500 e costare carissimo.

Che cosa hanno in comune i tre

In tutti e tre i casi la macchina è in piedi. Qualcosa ha risposto. Questo esclude già DNS, rete e hosting, ed è esattamente ciò che rende utile leggere questo codice prima di ogni altra cosa.

Se non risponde proprio nulla, il problema è altrove, e i primi quindici minuti si svolgono diversamente.

Due vicini vanno distinti, perché spesso vengono confusi con questa famiglia. Un 404 non è un guasto: è la risposta corretta a una richiesta per una pagina che non esiste, e si smista con altre regole. Un avviso di certificato non è affatto un codice di errore: il server risponde perfettamente, è il browser che si rifiuta di mostrare, e quel guasto non lascia traccia nei tuoi log.

La domanda che nessuno pone

Qualunque codice tu abbia ottenuto, la domanda utile viene dopo: per quanto tempo è stato restituito prima che tu lo sapessi? Un 500 che dura quattro minuti non è un evento. Lo stesso 500 scoperto l'indomani mattina da un cliente è un'altra storia, e la differenza non ha nulla a che vedere con il codice.

È anche l'unica parte che si può quantificare: quanto costa davvero un'ora di disservizio dipende molto meno dalla natura del guasto che dal tempo che è rimasto sullo schermo.