Mensagens de Status HTTP

Toda vez que um navegador carrega uma página, envia um formulário, ou seu JavaScript faz uma chamada fetch(), o servidor responde com um código de status HTTP de três dígitos. Esse código informa ao cliente se a requisição foi bem-sucedida, foi redirecionada, falhou por algo que o cliente fez, ou falhou no lado do servidor. O navegador usa isso automaticamente — ele segue redirecionamentos, exibe sua própria página de erro para alguns códigos e reutiliza conteúdo em cache para outros — mas como desenvolvedor você também lê esses códigos diretamente: um formulário é enviado e você ramifica na resposta, ou um fetch() é resolvido e você verifica response.ok (que é simplesmente "status no intervalo 200–299").

Aqui você pode encontrar a lista de códigos de status de resposta do Hypertext Transfer Protocol (HTTP). Esses códigos respondem à requisição que um cliente faz a um servidor — seja usando GET, POST ou outro método HTTP — e são agrupados em 5 classes pelo primeiro dígito. Conhecê-los ajuda a depurar links quebrados, URLs incorretas, envios de formulário com falha e respostas de API inesperadas. Vamos percorrer cada classe:

Tratando códigos de status em JavaScript

Quando você envia um formulário ou chama uma API com fetch(), a requisição é bem-sucedida (a promise é resolvida) mesmo quando o servidor retorna um erro 4xx ou 5xx — um 404 ou 500 ainda é uma resposta HTTP válida, não uma falha de rede. Portanto, você deve inspecionar o status por conta própria. O atalho útil é response.ok, que é true apenas para o intervalo 200–299; para qualquer outra coisa você ramifica em response.status para reagir adequadamente:

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}).`);
  }
});

Note que fetch() só rejeita em problemas genuínos de rede (sem conexão, bloqueio CORS, falha de DNS), portanto envolver a chamada em try…catch lida com esses casos, enquanto o if/else acima lida com o status HTTP em si.

1xx: Informação

2xx: Sucesso

3xx: Redirecionamento

Códigos não listados aqui (como 305 e 306) estão obsoletos, são raros ou são específicos de extensões.

4xx: Erro do Cliente

Códigos não listados aqui (como 419, 420 e vários no intervalo 423–431) são raros, específicos de frameworks ou não padronizados. Alguns — como 421 (Misdirected Request, usado em HTTP/2) e o 451 acima — são padronizados, mas incomuns no trabalho cotidiano.

5xx: Erro do Servidor

Capítulos Relacionados

O status que um servidor retorna frequentemente depende da própria requisição. Para se aprofundar, veja:

• Métodos HTTP — GET, POST e afins, que determinam como alguns redirecionamentos (302 vs 307) se comportam.
• Formulários HTML — como envios de formulário acionam requisições que podem retornar 303, 422 ou 429.
• HTML URL (Uniform Resource Locators) — os endereços para os quais redirecionamentos 3xx e respostas 404 apontam.

Prática