Codici di stato HTTP

I codici di stato HTTP sono numeri a tre cifre che un server invia nella risposta per descrivere il risultato della tua richiesta. 200 significa che la richiesta è riuscita, 404 significa che la pagina non è stata trovata, e 500 significa che il server ha incontrato un errore. La prima cifra raggruppa il codice in una delle cinque classi — 2xx è sempre un successo, 5xx è sempre un errore del server — quindi conoscere la classe ti dice immediatamente dove iniziare il debug: lato client o lato server.

La prima cifra definisce la classe: 1xx Informazionale (la richiesta è stata ricevuta ed è in corso, es. 100 Continue), 2xx Successo (ha funzionato, es. 200 OK), 3xx Reindirizzamento (devi andare altrove, es. 301 Moved Permanently), 4xx Errore del client (la tua richiesta è errata, es. 404 Not Found), e 5xx Errore del server (il server ha fallito, es. 500 Internal Server Error). Filtra per qualsiasi classe nello strumento qui sopra per vedere solo quel gruppo con le spiegazioni di ogni codice.

Quelli che incontrerai quotidianamente sono 200 OK, 201 Created, 204 No Content, i redirect 301 e 302, 304 Not Modified, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 429 Too Many Requests, 500 Internal Server Error, 502 Bad Gateway e 503 Service Unavailable. Attiva 'Solo comuni' nello strumento qui sopra per filtrare la lista completa fino a questo insieme ristretto, con cause e soluzioni per ciascuno.

200 OK è la risposta di successo standard — per un GET restituisce la risorsa nel corpo, per un POST restituisce il risultato dell'azione. 201 Created significa che un POST o PUT è riuscito e ha creato una nuova risorsa; il server di solito mette l'indirizzo di quella nuova risorsa in un header Location, es. Location: /utenti/42. Se stai costruendo un'API e crei una risorsa, restituisci 201 con un header Location — non 200 — così i client sanno dove trovare il nuovo oggetto.

404 significa che il server non ha trovato nulla a quell'URL — non esiste, è stato spostato, o il link è rotto. Risolvilo controllando l'URL per errori di battitura e maiuscole/minuscole errate, aggiungendo un redirect 301 dal vecchio indirizzo a quello nuovo, verificando le regole di routing o riscrittura del tuo server, e servendo una pagina 404 personalizzata utile. A differenza di 410 Gone, un 404 non promette che la risorsa sia sparita per sempre, quindi i motori di ricerca continuano a eseguire la scansione. MDN Web Docs copre bene la specifica, ma questo strumento mostra le cause comuni e le soluzioni direttamente accanto a ogni codice.

301 Moved Permanently indica che la risorsa ha una nuova sede definitiva, quindi i motori di ricerca trasferiscono i segnali di ranking al nuovo URL e aggiornano il loro indice — usalo quando cambi un URL in modo permanente. 302 Found è temporaneo: l'URL originale rimane canonico e mantiene il suo ranking, quindi usalo per spostamenti brevi come test A/B o una pagina di manutenzione. Per richieste non-GET usa 308 (permanente) o 307 (temporaneo), perché preservano il metodo HTTP invece di consentire ai browser di declassare un POST a un GET.

403 Forbidden significa che il server ha capito la tua richiesta ma rifiuta di autorizzarla — e a differenza del 401, inviare credenziali non sarà d'aiuto. Le cause tipiche sono permessi o scope mancanti sull'account, permessi file errati sul server (es. un file impostato a 600 invece di 644), un blocco IP o una regola WAF, oppure un elenco di directory disabilitato senza file indice presente. Controlla i ruoli dell'account, i permessi dei file e qualsiasi lista di controllo degli accessi. Alcuni server restituiscono deliberatamente 403 invece di 404 per evitare di rivelare che una risorsa esiste.

Tutti sono errori server 5xx ma significano cose diverse. 500 Internal Server Error è un generico 'qualcosa si è rotto' — di solito un'eccezione non gestita o un bug nell'applicazione. 502 Bad Gateway significa che un proxy ha ricevuto una risposta non valida dall'app server upstream (spesso è crashato). 503 Service Unavailable significa che il server è temporaneamente inattivo o sovraccarico — dovrebbe includere un header Retry-After. 504 Gateway Timeout significa che l'upstream era raggiungibile ma troppo lento per rispondere in tempo. Inizia dai log del server per distinguere questi casi nella pratica.

429 significa che hai superato un limite di frequenza — troppe richieste in una finestra temporale data. Il server dovrebbe includere un header Retry-After che ti dice quanto tempo aspettare. Risolvilo rispettando quell'header, aggiungendo un backoff esponenziale tra i tentativi, memorizzando nella cache le risposte per ridurre il volume di richieste, oppure richiedendo una quota maggiore. È comune sulle API pubbliche e sugli endpoint di login che si proteggono dagli abusi. GitHub, Stripe e Twitter/X usano tutti 429 per il rate limiting delle API.

Gli errori 4xx sono colpa del client — la richiesta stessa è errata, quindi reinviarla invariata non aiuterà (400 Bad Request, 401 Unauthorized, 404 Not Found). Gli errori 5xx sono colpa del server — la tua richiesta potrebbe essere perfettamente valida ma il server non è riuscito a soddisfarla (500, 502, 503), quindi la stessa richiesta può avere successo una volta che il server si riprende. Correggi la richiesta per i 4xx, correggi il server per i 5xx. Questa distinzione è importante per la logica di retry: riprova solo sui 5xx con backoff esponenziale, non sui 4xx.

I principali sono 200 OK (ogni pagina indicizzabile dovrebbe restituirlo), 301 Moved Permanently (trasferisce il ranking a un nuovo URL durante le migrazioni), 302 Found (temporaneo — mantiene il ranking sull'URL originale), 404 Not Found e 410 Gone (comunicano ai crawler che una pagina è mancante; 410 viene rimosso dall'indice più velocemente perché è permanente), e 503 Service Unavailable (il codice SEO-safe per la manutenzione pianificata — dice a Google di tornare più tardi invece di de-indicizzare la pagina).

401 Unauthorized significa in realtà 'non autenticato' — non hai dimostrato chi sei, quindi inviare credenziali valide (un token, una chiave API, o una sessione di login) può risolvere il problema; il server dovrebbe rispondere con un header WWW-Authenticate. 403 Forbidden significa che sei autenticato ma semplicemente non sei autorizzato ad accedere a questa risorsa — credenziali migliori non aiuteranno, hai bisogno di permessi diversi. Regola pratica: 401 = chi sei tu, 403 = non puoi farlo.

Tutti e quattro sono redirect, ma 307 e 308 garantiscono che il metodo HTTP originale e il corpo vengano preservati, mentre 301 e 302 storicamente consentono ai client di passare da un POST a un GET sulla richiesta reindirizzata. Quindi 301 (permanente) e 302 (temporaneo) vanno bene per i semplici redirect di pagina, ma per un endpoint che riceve dati POST o PUT, usa 308 per gli spostamenti permanenti e 307 per quelli temporanei, per mantenere il metodo intatto ed evitare perdite di dati.

I codici nell'intervallo 520–530 sono codici non standard che Cloudflare restituisce quando qualcosa va storto tra Cloudflare e il tuo server di origine — non fanno parte della specifica HTTP ufficiale ma li vedrai continuamente dietro Cloudflare. 520 significa che l'origine ha inviato una risposta vuota o inattesa, 521 significa che l'origine ha rifiutato la connessione (è inattiva o sta bloccando Cloudflare), 522 significa che la connessione TCP è scaduta, 523 significa che l'origine non è raggiungibile, 524 significa che l'origine si è connessa ma non ha risposto entro 100 secondi, 525 e 526 sono errori di handshake SSL e certificato non valido, e 530 è di solito un errore DNS dell'origine abbinato a un codice 1xxx. Cerca qualsiasi di questi numeri qui sopra per cause e soluzioni.

MDN Web Docs è il riferimento autorevole della specifica ma non ha una barra di ricerca live, nessun filtro per classe, e nessuna vista cheat sheet compatta — si naviga una pagina per codice. httpstatuses.com mostra i codici in una griglia ma omette le cause e le soluzioni pratiche. restapitutorial.com copre le convenzioni REST senza una ricerca interattiva. HTTP.cat è un sito divertente (ogni codice corrisponde a una foto di un gatto) ma poco pratico per il debug reale. Questo strumento combina un riferimento ricercabile, filtro per classe, modalità cheat sheet, cause e soluzioni in italiano semplice, e i codici Cloudflare 5xx che la maggior parte dei riferimenti ignora — tutto in una pagina che funziona offline senza pubblicità o registrazione.

Completamente. L'intera lista è distribuita come dati statici all'interno della pagina, quindi ogni ricerca, filtro e consultazione viene eseguita localmente nel tuo browser — nulla viene caricato, registrato, o inviato a un server. Questo significa anche che si carica istantaneamente e continua a funzionare offline una volta che la pagina è aperta. Nessuna registrazione, nessun account, nessun limite di richieste, e nessun paywall. Solo un riferimento veloce e privato che funziona altrettanto bene sul telefono come sul desktop.