Códigos de status HTTP
Códigos mais vistos em APIs e CDNs. Experimentais raros ficam de fora.
| Código | Nome | Significado |
|---|---|---|
| 200 | OK | Sucesso com corpo |
| 201 | Criado | Recurso criado |
| 204 | Sem conteúdo | Sucesso, corpo vazio |
| 301 | Movido permanentemente | Redirecionamento permanente |
| 302 | Encontrado | Redirecionamento temporário |
| 304 | Não modificado | Usar cópia em cache |
| 400 | Pedido inválido | Pedido do cliente inválido |
| 401 | Não autorizado | Autenticação necessária ou falhou |
| 403 | Proibido | Autenticado, mas negado |
| 404 | Não encontrado | O recurso não existe |
| 405 | Método não permitido | Método HTTP errado |
| 408 | Tempo limite do pedido | Cliente muito lento |
| 409 | Conflito | Conflito de estado |
| 410 | Perdido | Removido permanentemente |
| 422 | Entidade não processável | Semântica inválida |
| 429 | Muitas solicitações | Limite de requisições |
| 500 | Erro interno do servidor | Falha do servidor |
| 502 | Gateway inválido | Resposta upstream inválida |
| 503 | Serviço indisponível | Sobrecarregado ou fora do ar |
| 504 | Tempo limite do gateway | Tempo limite do upstream |
Notas
- 401 vs 403: credenciais ausentes/falhas versus autenticado sem permissão.
- O CDN pode devolver 5xx se a origem não responder.
As cinco classes de códigos de status
O primeiro dígito indica quem é o responsável e, de forma genérica, o que aconteceu. Os 1xx são informações e raramente aparecem para o cliente. Os 2xx indicam sucesso — 200 OK com corpo, 204 No Content sem corpo, 206 para download parcial. Os 3xx significam que o recurso está em outro lugar. Os 4xx indicam que a solicitação em si está errada: sintaxe inválida, credenciais ausentes ou limite de taxa atingido. Os 5xx significam que o servidor falhou mesmo com uma solicitação correta. Só de ler o primeiro dígito já se sabe se é preciso corrigir o cliente ou escalar para o lado do servidor.
Escolhendo o redirecionamento adequado
301 e 308 ambos indicam permanência; 302 e 307 indicam temporariedade. A diferença está no tratamento do método: 301 e 302 historicamente permitem que o cliente converta um POST em GET, enquanto 307 e 308 preservam o método e o corpo originais, o que é relevante para APIs e envios de formulários. Use 301 quando uma URL tiver se mudado de fato e para sempre, e 302 ou 307 para roteamento temporário, como páginas de manutenção ou testes A/B. Cuidado com cadeias — cada hop extra custa latência e autoridade dos links, então redirecione diretamente para o destino final.
Resolvendo erros 4xx
401 significa que a autenticação está ausente ou falhou, portanto enviar credenciais válidas pode resolver; 403 significa que a solicitação foi compreendida e autenticada, mas não é permitida, e repetir com as mesmas credenciais não ajudará. 404 indica que o recurso não existe; 410 sinaliza que ele existia e foi removido propositalmente. 429 significa que você atingiu o limite de taxa e deve recuar, honrando o cabeçalho Retry-After. 400 geralmente indica entrada malformada, 405 significa que o método está errado para aquela URL e 422 indica que a sintaxe era válida, mas o conteúdo falhou na validação.
Interpretando códigos 5xx
500 é um erro interno genérico; 502 Bad Gateway significa que um servidor upstream retornou algo inutilizável; 503 indica que o serviço está temporariamente indisponível ou sobrecarregado; 504 significa que um servidor upstream esgotou o tempo esperado. Esses são problemas do servidor, não do chamador, então a solução é tentar novamente com backoff, verificar a saúde do upstream ou reduzir a carga. Uma CDN pode emitir 502, 503 ou 504 em nome de uma origem que não consegue alcançar, motivo pelo qual o mesmo erro pode vir de dois lugares muito diferentes — verifique os cabeçalhos server e cache-status para descobrir qual.
Códigos de status na prática: APIs e cache
Dois usos cotidianos merecem atenção. Primeiro, cache: 200 com um cabeçalho Cache-Control pode ser armazenado, 304 Not Modified informa ao cliente para reutilizar sua cópia, e um 5xx não deve ser armazenado em cache. Segundo, APIs: um POST que cria um recurso deve retornar 201 com um cabeçalho Location, DELETE frequentemente retorna 204 e um PATCH que não altera nada pode retornar 200 ou 204. Clientes bem comportados fazem ramificação pela classe primeiro (2xx, 4xx, 5xx) e só então pelo código exato, o que mantém a lógica de retry e backoff simples e previsível.
Perguntas frequentes
- O que significa o código HTTP 403?
- 403 Forbidden significa que o servidor entendeu e autenticou a requisição, mas recusa dar acesso ao recurso. Diferente do 401, entrar novamente não resolve.
- Qual é a diferença entre os redirecionamentos HTTP 301 e 302?
- 301 indica uma mudança permanente: clientes e mecanismos de busca devem usar a nova URL. 302 é um redirecionamento temporário e a URL original continua válida.
- O que significa HTTP 429 e como resolver?
- 429 significa que você atingiu um limite de requisições. Reduza a frequência e respeite o cabeçalho Retry-After se o servidor o enviar.