1. O Que Sao Codigos HTTP

Os codigos de status HTTP sao respostas numericas de tres digitos que um servidor envia ao cliente para indicar o resultado de uma requisicao. Eles sao parte fundamental do protocolo HTTP desde sua criacao por Tim Berners-Lee no CERN em 1991 e foram formalizados na RFC 1945 (HTTP/1.0) e posteriormente na RFC 7231 (HTTP/1.1).

Para qualquer desenvolvedor web, conhecer os codigos HTTP e essencial — tanto para construir APIs corretas quanto para depurar problemas em producao, configurar servidores e entender o comportamento de browsers e proxies.

2. As Cinco Categorias

O primeiro digito do codigo define a categoria da resposta:

• 1xx — Informacional: respostas provisorias. O servidor recebeu a requisicao e o cliente pode continuar. Raramente visto na pratica, exceto em WebSockets (101) e Early Hints (103).
• 2xx — Sucesso: a requisicao foi recebida, entendida e aceita com sucesso. O 200 OK e o mais comum, mas 201 Created, 204 No Content e 206 Partial Content tem usos especificos importantes.
• 3xx — Redirecionamento: o cliente precisa tomar uma acao adicional para completar a requisicao. Fundamental para SEO (301 vs 302) e para padroes de design como Post/Redirect/Get (303).
• 4xx — Erro do Cliente: a requisicao contem um erro do lado do cliente — seja sintaxe errada, autenticacao ausente, recurso nao encontrado ou permissao negada.
• 5xx — Erro do Servidor: o servidor reconhece que ocorreu um erro, mas nao consegue processar a requisicao. Indica problemas na infraestrutura ou no codigo da aplicacao.

"Um codigo HTTP correto e a diferenca entre uma API que comunica claramente e uma que deixa o cliente no escuro. Use-os com precisao."

3. Os Codigos Mais Usados no Dia a Dia

Alguns codigos aparecem em praticamente todo projeto web:

• 200 OK: sucesso generico — GET retornou o recurso, POST executou a acao.
• 201 Created: use apos criar um recurso via POST ou PUT; inclua Location no header.
• 204 No Content: ideal para DELETE bem-sucedido ou PUT sem corpo de resposta.
• 301 Moved Permanently: redireciona para sempre; mecanismos de busca transferem o PageRank.
• 400 Bad Request: parametros invalidos, JSON malformado, campos obrigatorios ausentes.
• 401 Unauthorized: nao autenticado — o cliente precisa fazer login.
• 403 Forbidden: autenticado mas sem permissao — diferente do 401.
• 404 Not Found: recurso nao existe — o mais conhecido de todos.
• 422 Unprocessable Content: dados validos sintaticamente mas com erros de validacao semantica.
• 429 Too Many Requests: rate limiting — o cliente excedeu o limite de requisicoes.
• 500 Internal Server Error: erro nao tratado no servidor.

4. Depurando Erros HTTP

Quando um erro HTTP aparece em producao, o codigo e o primeiro indicador do que investigar:

• Erros 4xx recorrentes: verifique os logs de requisicao — URL errada, headers faltando, tokens expirados.
• 503 Service Unavailable: verifique a saude dos processos da aplicacao e a carga do servidor.
• 502/504: problemas entre o proxy reverso e o servidor de aplicacao — verifique timeouts e conectividade interna.
• Muitos 301/302: podem indicar loops de redirecionamento — use ferramentas como Redirect Checker.

5. HTTP no Contexto de APIs REST

Em APIs RESTful, o uso correto dos codigos HTTP e fundamental para criar interfaces previsveis e autodescritivas. A convencao mais aceita e:

• GET de colecao → 200; GET de recurso inexistente → 404.
• POST para criar → 201 com Location; POST de acao → 200.
• PUT/PATCH para atualizar → 200 com corpo ou 204 sem corpo.
• DELETE bem-sucedido → 204; DELETE de recurso inexistente → 404.
• Erros de validacao → 422 com detalhes dos campos no corpo.
• Conflito de estado → 409 (ex: email ja cadastrado).

6. Perguntas Frequentes

Qual a diferenca entre 401 e 403?

401 significa "voce nao esta autenticado" — o servidor nao sabe quem voce e. 403 significa "voce esta autenticado, mas nao tem permissao" — o servidor sabe quem voce e, mas recusa o acesso. Use 401 para proteger recursos que requerem login, e 403 quando o usuario logado nao tem o papel ou permissao necessarios.

Quando usar 301 vs 302 para redirecionamentos?

Use 301 (permanente) quando a URL mudou definitivamente — mecanismos de busca transferem o ranking e os clientes devem atualizar seus bookmarks. Use 302 (temporario) quando a mudanca e provisoria — o cliente deve continuar usando a URL original. Para APIs, 307 e 308 sao preferidos pois preservam o metodo HTTP.

O que e o codigo 418 I'm a Teapot?

E um Easter Egg criado na RFC 2324 em 1998 como brincadeira de Primeiro de Abril. O "Hyper Text Coffee Pot Control Protocol" define que um bule de cha deve retornar 418 se solicitado a fazer cafe. Amplamente adotado como resposta humoristica em APIs, e inclusive implementado em alguns servidores populares.

Por que 404 e tao famoso?

O 404 e o codigo de erro mais visivel para usuarios finais, pois aparece quando uma URL digitada ou um link quebrado nao leva a lugar nenhum. Sua ubiquidade o tornou parte da cultura da internet — e um dos poucos termos tecnicos amplamente reconhecidos fora da area de tecnologia.