O que são códigos de status HTTP?

A resposta curta do servidor

Toda vez que um cliente (navegador, app mobile, consumidor de API) envia uma requisição HTTP, o servidor envia de volta uma resposta. A primeira coisa nessa resposta é um número de três dígitos chamado código de status.

Esse número é o resumo rápido do servidor sobre o que aconteceu:

HTTP/1.1 200 OK

O 200 diz ao cliente: "Sua requisição foi recebida, entendida e processada com sucesso." Não é preciso ler todo o corpo da resposta para saber o resultado: o código de status dá a resposta imediatamente.

As cinco famílias

Os códigos de status HTTP são organizados em cinco categorias baseadas no primeiro dígito:

Pense nisso como um sistema de semáforo:

• 2xx = Luz verde: tudo deu certo
• 3xx = Luz amarela: vá para outro lugar
• 4xx = Luz vermelha para você: você cometeu um erro
• 5xx = Luz vermelha para o servidor: ele quebrou

Anatomia de uma linha de status

O código de status aparece na primeira linha de toda resposta HTTP, chamada linha de status:

HTTP/1.1 200 OK
│         │   │
│         │   └─ Frase de razão (descrição legível por humanos)
│         └───── Código de status (o número de três dígitos)
└─────────────── Versão HTTP

A frase de razão (como "OK", "Not Found", "Created") é apenas uma dica para humanos lendo tráfego HTTP bruto. Aplicações devem confiar no código numérico, não no texto.

Por que códigos de status importam

Para desenvolvedores

Códigos de status determinam como sua aplicação trata respostas:

if response.status == 200
  # Mostrar os dados ao usuário
elsif response.status == 404
  # Mostrar página "não encontrado"
elsif response.status == 500
  # Mostrar página "algo deu errado"
end

Sem códigos de status, você teria que analisar todo o corpo da resposta para descobrir o que aconteceu: lento, propenso a erros e inconsistente entre APIs.

Para navegadores

Navegadores usam códigos de status para tomar decisões automáticas:

• 301 → seguir automaticamente o redirecionamento e lembrar dele da próxima vez
• 304 → usar a versão em cache em vez de baixar novamente
• 401 com WWW-Authenticate: Basic → pedir usuário e senha
• 204 → ficar na página atual em vez de navegar

Para mecanismos de busca

Google e outros crawlers usam códigos de status para entender seu site:

• 200 → indexar esta página
• 301 → transferir ranking para a nova URL
• 404 → remover esta página dos resultados de busca
• 503 → voltar depois, não desindexar

Para infraestrutura

Load balancers, CDNs e ferramentas de monitoramento todos dependem de códigos de status:

• Health checks esperam 200 para confirmar que o servidor está vivo
• CDNs fazem cache de respostas baseadas em códigos de status
• Alertas de monitoramento disparam em picos de 5xx

Os códigos de status mais comuns

Você não precisa memorizar todos os códigos de status (existem mais de 60). Aqui estão os que você encontrará com mais frequência:

Códigos de status são um contrato

Códigos de status são parte do contrato da API entre cliente e servidor. Quando um servidor retorna 200 OK, ele está fazendo uma promessa: "A requisição teve sucesso e o corpo da resposta contém o que você pediu."

Usar o código de status errado quebra esse contrato:

• Retornar 200 com uma mensagem de erro no corpo → confunde clientes automatizados
• Retornar 500 para um erro de validação → faz parecer um bug do servidor
• Retornar 404 para um recurso não autorizado → esconde o problema real, a menos que esconder que ele existe seja a intenção (o GitHub responde 404 para repositórios privados que você não pode ver)

Escolher o código de status certo não é pedantismo: é como a web funciona de forma confiável.

O que este curso cobre

Este curso foca na família 2xx Sucesso. Você aprenderá:

• 200 OK: a resposta de sucesso padrão
• 201 Created: quando um novo recurso nasce
• 204 No Content: sucesso sem nada para retornar
• 202 Accepted e 206 Partial Content: códigos de sucesso especializados
• Como escolher o código de sucesso certo para cada situação
• Como Rails implementa esses códigos

Resumo