Messaggi di Stato HTTP

Ogni volta che un browser carica una pagina, invia un modulo o il tuo JavaScript esegue una chiamata fetch(), il server risponde con un codice di stato HTTP a tre cifre. Questo codice indica al client se la richiesta è riuscita, è stata reindirizzata, è fallita a causa di qualcosa fatto dal client, o è fallita lato server. Il browser lo utilizza automaticamente — segue i reindirizzamenti, mostra la propria pagina di errore per alcuni codici e riutilizza il contenuto memorizzato nella cache per altri — ma come sviluppatore leggi questi codici anche direttamente: un modulo viene inviato e ti ramifichi in base alla risposta, oppure una fetch() si risolve e controlli response.ok (che è semplicemente "stato nell'intervallo 200–299").

Qui puoi trovare l'elenco dei codici di stato delle risposte del Protocollo di Trasferimento Ipertestuale (HTTP). Questi codici rispondono alla richiesta che un client fa a un server — che la richiesta utilizzi GET, POST o un altro metodo HTTP — e sono raggruppati in 5 classi in base alla prima cifra. Conoscerli ti aiuta a diagnosticare link interrotti, URL errati, invii di moduli falliti e risposte API inattese. Esaminiamo ogni classe:

Gestione dei codici di stato in JavaScript

Quando invii un modulo o chiami un API con fetch(), la richiesta ha successo (la promise si risolve) anche quando il server restituisce un errore 4xx o 5xx — un 404 o 500 è comunque una risposta HTTP valida, non un errore di rete. Devi quindi ispezionare tu stesso lo stato. La scorciatoia pratica è response.ok, che è true solo per l'intervallo 200–299; per qualsiasi altro caso ti ramifichi su response.status per reagire in modo appropriato:

const form = document.querySelector("#signup");

form.addEventListener("submit", async (event) => {
  event.preventDefault();

  const response = await fetch("/api/signup", {
    method: "POST",
    body: new FormData(form),
  });

  if (response.ok) {
    // 200–299: success
    window.location.href = "/welcome";
  } else if (response.status === 401) {
    showMessage("Please log in first.");
  } else if (response.status === 422) {
    // Validation errors returned as JSON
    const data = await response.json();
    showMessage(data.error);
  } else if (response.status === 429) {
    // Rate limited — respect the Retry-After header
    const wait = response.headers.get("Retry-After");
    showMessage(`Too many attempts. Try again in ${wait}s.`);
  } else if (response.status >= 500) {
    showMessage("Server error — please try again later.");
  } else {
    showMessage(`Unexpected error (${response.status}).`);
  }
});

Nota che fetch() rigetta solo in caso di problemi di rete genuini (nessuna connessione, blocco CORS, errore DNS), quindi racchiudere la chiamata in un try…catch gestisce quelli, mentre il blocco if/else sopra gestisce lo stato HTTP stesso.

1xx: Informazione

2xx: Successo

3xx: Reindirizzamento

I codici non elencati qui (come 305 e 306) sono deprecati, rari o specifici di alcune estensioni.

4xx: Errore del Client

I codici non elencati qui (come 419, 420 e diversi nell'intervallo 423–431) sono rari, specifici di framework o non standard. Alcuni — come il 421 (Misdirected Request, utilizzato in HTTP/2) e il 451 sopra — sono standardizzati ma non comuni nel lavoro quotidiano.

5xx: Errore del Server

Capitoli Correlati

Lo stato restituito da un server dipende spesso dalla richiesta stessa. Per approfondire, consulta:

• Metodi HTTP — GET, POST e altri, che determinano come si comportano alcuni reindirizzamenti (302 vs 307).
• Moduli HTML — come gli invii di moduli attivano richieste che possono restituire 303, 422 o 429.
• URL HTML (Uniform Resource Locators) — gli indirizzi a cui puntano i reindirizzamenti 3xx e le risposte 404.

Pratica