Codici di stato 4xx spiegati: cosa significano davvero gli errori client

Cosa dice la classe 4xx

L'RFC 9110 definisce la classe 4xx come "Client Error": il server ritiene che il client abbia commesso un errore. Questo copre una richiesta per qualcosa che non esiste, una richiesta priva delle credenziali necessarie, una richiesta che il server rifiuta per motivi di policy, e una richiesta malformata o troppo grande.

Tre proprietà della classe contano mentre ne stai debuggando una:

• Un 4xx è una risposta finale per quella richiesta così com'è stata inviata. Ripetere la richiesta identica di solito produce lo stesso identico codice.
• Il corpo della risposta è pensato per essere una spiegazione leggibile da un essere umano. Ecco perché esistono le pagine di errore personalizzate, e perché una pagina 404 vuota è un'occasione sprecata.
• Alcune risposte 4xx sono memorizzabili in cache per impostazione predefinita. L'RFC 9111 elenca 404, 405, 410 e 414 tra i codici che una cache può memorizzare euristicamente, quindi un 404 sbagliato può sopravvivere al bug che lo ha causato.

I codici 4xx che incontrerai

• 400 Bad Request: la richiesta è malformata e il server non riesce ad analizzarla. Spesso una query string errata, un'intestazione cookie sovradimensionata o un proxy rotto davanti all'app.
• 401 Unauthorized: è richiesta l'autenticazione ed è mancante o non valida. Il server deve inviare un'intestazione WWW-Authenticate che dice al client come autenticarsi.
• 403 Forbidden: il server ha compreso la richiesta e la rifiuta. Le credenziali non aiuteranno, perché il rifiuto è una decisione di policy e non un fallimento di autenticazione.
• 404 Not Found: nessuna rappresentazione attuale esiste a quell'URL, oppure il server non ammette che ne esista una. Trattato in dettaglio nella guida al 404.
• 405 Method Not Allowed: l'URL esiste ma non per quel metodo. Il server deve elencare i metodi che accetta in un'intestazione Allow.
• 408 Request Timeout: il client ci ha messo troppo a inviare la richiesta. Diverso da un 504, dove il ritardo sta dietro al server.
• 410 Gone: la risorsa esisteva ed è stata rimossa deliberatamente, e si prevede che sia permanente.
• 413 Content Too Large e 414 URI Too Long: la richiesta ha superato un limite configurato, di solito un tetto di upload o un limite di dimensione delle intestazioni.
• 429 Too Many Requests: è stato raggiunto un limite di frequenza. Questo in particolare morde le configurazioni di monitoraggio.

Quando un 4xx è in realtà una configurazione errata del server

L'etichetta "errore client" riguarda i ruoli del protocollo, non la colpa. La maggior parte dei codici 4xx che compaiono su un sito di produzione sano sono causati da qualcosa dal tuo lato. Una regola di rewrite o di routing che non corrisponde più trasforma URL validi in 404 su un'intera directory, e il segno rivelatore è un 404 su molti URL contemporaneamente invece che su uno solo. Una build che smette di generare un asset con hash fa la stessa cosa a livello di file: ogni pagina richiede un file che restituisce 404, così la pagina si visualizza ma sembra rotta.

I livelli di sicurezza spiegano gran parte del resto. Una regola WAF, un filtro anti-bot o un geo-blocco possono restituire 403 al traffico reale, e sono facili da perdere perché di solito passano per l'indirizzo IP dell'ufficio. Una modifica all'autenticazione che lascia una pagina rispondere 401 quando dovrebbe essere pubblica è un 4xx causato interamente dal server. Lo è anche un 400 o 413 da un reverse proxy il cui limite di intestazione o corpo è più piccolo di quello dell'applicazione, per una richiesta che l'app avrebbe accettato.

Come diagnosticare un 4xx sul tuo sito

1. Leggi prima il codice esatto e le intestazioni. Non giudicare dalla pagina di errore, che potrebbe essere generica:

   curl -sS -o /dev/null -D - https://example.com/broken-page

   Questo mostra la riga di stato più Allow, WWW-Authenticate, Retry-After e qualsiasi intestazione di identificazione del server o della CDN.
2. Decidi se è un singolo URL o uno schema. Un singolo URL indica un link o una pagina eliminata. Un intero prefisso di percorso indica routing, permessi o un deploy.
3. Controlla chi ha risposto. Confronta la risposta dal nodo edge della CDN con la risposta dall'origine. Un 403 che esiste solo all'edge è una regola WAF o anti-bot, non la tua applicazione.
4. Prova un'identità client diversa. Uno user agent diverso, una sessione non autenticata o una rete diversa possono trasformare il codice da 403 a 200, il che localizza il blocco immediatamente.
5. Leggi la riga di log del server per quella richiesta. I log del server web e dell'applicazione registrano quale regola o handler ha prodotto il codice. Questo è il passaggio che di solito conclude l'indagine.
6. Correggi, poi svuota le cache. Poiché diversi codici 4xx sono memorizzabili in cache, una pagina corretta può continuare a servire il vecchio errore da una cache CDN o browser finché la voce non viene invalidata.

Trovare le pagine 4xx che non visiti mai

Un 4xx non mette giù un server, ed ecco perché passa inosservato. Il sito si carica, la homepage va bene, e una sezione restituisce 404 o 403 per tutti tranne che per te. Un controllo HTTP pianificato confronta il codice che riceve con quello che ti aspetti, così una pagina che inizia a rispondere 403 invece di 200 fa scattare un avviso invece di aspettare un ticket di supporto. Anche da dove gira il controllo conta. HostTracker controlla da più di 300 postazioni in 158 città, così un geo-blocco o una regola WAF regionale si mostra come una differenza reale tra ubicazioni invece che come un mistero. Se il codice che fallisce è invece 500, 502 o 503, la causa sta dal lato server e la guida alla famiglia 5xx è il punto da cui iniziare.