Codici di stato 5xx spiegati: quando il problema è il tuo server
Un codice di stato 5xx significa che è fallita la tua infrastruttura, non la richiesta del visitatore. Il server ha accettato la richiesta, l'ha compresa, e poi non è riuscito a produrre una risposta valida, quindi ogni 5xx sul tuo sito è un incidente di tua responsabilità.
Cosa separa 5xx da 4xx
L'RFC 9110 definisce 5xx come "Server Error": il server è consapevole di aver commesso un errore oppure è incapace di eseguire il metodo richiesto. Questa è l'intera distinzione. Un 404 dice "qui non c'è nulla". Un 500 dice "qui c'è qualcosa e mi sono rotto mentre lo producevo".
Ne seguono due conseguenze. Primo, un 5xx è di solito ritentabile, perché la stessa richiesta potrebbe benissimo avere successo un secondo dopo una volta che il componente che fallisce si riprende. Secondo, i motori di ricerca trattano un 5xx come un segnale temporaneo e rallentano la scansione invece di deindicizzare immediatamente, mentre un 5xx persistente per giorni finisce comunque per costarti pagine indicizzate.
Quale salto è fallito
Leggi un codice 5xx come una mappa di dove è morta la richiesta. Quasi ogni sito moderno mette almeno un proxy davanti all'applicazione, quindi il codice ti dice quale lato di quel confine è fallito.
| Codice | Chi lo ha prodotto | Cosa è successo |
|---|---|---|
| 500 Internal Server Error | L'applicazione stessa | Eccezione non gestita o condizione imprevista dentro l'app |
| 501 Not Implemented | Il server | Il metodo di richiesta non è supportato affatto |
| 502 Bad Gateway | Il proxy, la CDN o il load balancer | Il backend ha risposto, ma con qualcosa di non valido, oppure ha chiuso la connessione |
| 503 Service Unavailable | Il server o il proxy, deliberatamente | Sovraccarico o in manutenzione, e rifiuta il lavoro di proposito |
| 504 Gateway Timeout | Il proxy, la CDN o il load balancer | Il backend non ha mai risposto in tempo |
| 505 HTTP Version Not Supported | Il server | La versione del protocollo nella richiesta non è supportata |
502, 503 e 504 portano il maggior valore diagnostico, perché ognuno nomina un guasto diverso dello stesso backend: risposta non valida, risposta rifiutata, nessuna risposta. La guida al 502 Bad Gateway copre il primo di essi in profondità, incluse le righe di log del proxy che identificano il guasto esatto.
Cause comuni dietro le risposte 5xx
- Crash dell'applicazione. Un'eccezione non gestita, una connessione al database fallita o un valore nullo in un punto inatteso produce 500 su qualunque rotta tocchi il percorso di codice rotto.
- Processo backend non in esecuzione. Un app server fermo, un pool PHP-FPM morto o un container che ha fallito il proprio controllo di salute non danno al proxy nulla con cui parlare, il che emerge come 502.
- Esaurimento delle risorse. Memoria esaurita, descrittori di file esauriti, thread worker esauriti o connessioni al database esaurite. Di solito inizia come errori intermittenti sotto carico prima di diventare costante.
- Dipendenze lente. Una query lenta, un'API di terze parti lenta o un avvio a freddo spinge il tempo di risposta oltre il timeout del proxy e si trasforma in 504.
- Deployment e riavvii. Qualsiasi finestra in cui il vecchio processo si è fermato e il nuovo non ha ancora iniziato a servire produce un picco di 502 o 503.
- Errori di configurazione. Un indirizzo upstream sbagliato, una configurazione TLS malfatta tra proxy e backend, oppure una discrepanza di protocollo come parlare HTTP a una porta HTTPS.
- Disco pieno. Una causa sottovalutata. I log o i file temporanei riempiono il volume, le sessioni o le cache smettono di scrivere, e l'applicazione inizia a fallire in modi che sembrano casuali.
Come procedere con un 5xx
- Conferma il codice e la sua origine. Recupera le intestazioni direttamente e guarda quale componente ha firmato la risposta:
Un'intestazionecurl -sS -o /dev/null -D - https://example.com/Server:o della CDN sull'errore ti dice se l'edge o l'origine lo ha generato. - Testa l'origine direttamente, saltando il proxy. Se il backend risponde 200 sulla propria porta mentre l'URL pubblico risponde 502, il guasto è nel livello proxy o nel collegamento tra i due.
- Leggi poi il log di errore del proxy, non il log dell'applicazione. I reverse proxy nominano il guasto con precisione, per esempio
connect() failed (111: Connection refused)oppureupstream timed out, il che separa immediatamente "backend giù" da "backend lento". - Poi leggi il log dell'applicazione. Per un 500, lo stack trace è la risposta. Per 502 e 504 l'applicazione spesso non registra nulla affatto, e quell'assenza è essa stessa informativa.
- Controlla le risorse sull'host. Memoria, disco, conteggio delle connessioni e saturazione dei worker. Un 5xx intermittente sotto traffico è quasi sempre un limite raggiunto.
- Guarda cosa è cambiato. Deployment, invii di configurazione, rinnovi di certificati e aggiornamenti di dipendenze spiegano una grande quota degli inizi improvvisi di 5xx.
Catturare errori 5xx intermittenti
Gli errori 5xx sono spesso intermittenti, il che è ciò che li rende difficili da catturare a mano: la pagina che ricarichi funziona, e quella che ha caricato il tuo cliente no. Un controllo HTTP pianificato gira continuamente e campiona il sito molto più spesso di quanto tu possa fare, così una serie di errori diventa visibile come uno schema invece che come lamentele sparse. Controllare da molte ubicazioni separa anche un vero guasto del server da un problema di instradamento o di edge che riguarda solo parte del mondo, motivo per cui il monitoraggio distribuito della disponibilità usa postazioni di controllo distribuite tra le regioni invece che un singolo punto di osservazione. Se il codice fallito risulta essere invece 403, 404 o 429, la richiesta non ha mai raggiunto un backend rotto, e la guida alla famiglia 4xx è il punto di partenza giusto.