Códigos de status HTTP são números de três dígitos retornados por servidores em resposta a requisições de clientes. Eles indicam se uma requisição foi bem-sucedida, falhou devido a erro do cliente, falhou devido a erro do servidor, ou requer ação adicional como um redirecionamento. Toda resposta HTTP inclui exatamente um código de status, tornando-os a primeira informação que um cliente ou intermediário usa para determinar o que fazer a seguir.
Como Funcionam os Códigos de Status HTTP
As Cinco Classes de Códigos de Status
Códigos de status são agrupados em cinco classes pelo seu primeiro dígito:
| Classe | Intervalo | Significado | Exemplo |
|---|---|---|---|
| 1xx | 100-199 | Informativo | 100 Continue |
| 2xx | 200-299 | Sucesso | 200 OK, 201 Created |
| 3xx | 300-399 | Redirecionamento | 301 Moved Permanently, 304 Not Modified |
| 4xx | 400-499 | Erro do Cliente | 400 Bad Request, 404 Not Found |
| 5xx | 500-599 | Erro do Servidor | 500 Internal Server Error, 502 Bad Gateway |
A frase de motivo após o código (“OK”, “Not Found”) é apenas informativa. Clientes devem usar o código numérico para tomada de decisão (RFC 9110).
Códigos de Status e Cache
Nem todos os códigos de status devem ser cacheados. A RFC 9111 define a cacheabilidade padrão:
| Código de Status | Cacheável por Padrão |
|---|---|
| 200, 203, 204, 206, 300, 301, 404, 410 | Sim (a menos que Cache-Control proíba) |
| 302, 307, 308 | Varia por implementação |
| 304 | Sim (valida conteúdo cacheado) |
| Outros 4xx (400, 401, 403, etc.) | Não |
| 5xx | Não |
Códigos de Status e Comportamento de Retry
Clientes e proxies usam códigos de status para decidir se devem tentar novamente:
| Código | Retry Seguro? | Comportamento de Retry |
|---|---|---|
| 408 Request Timeout | Sim | Tentar novamente imediatamente |
| 429 Too Many Requests | Sim | Tentar após atraso do Retry-After |
| 502 Bad Gateway | Métodos idempotentes apenas | Tentar com backoff |
| 503 Service Unavailable | Sim | Tentar após atraso do Retry-After |
| 504 Gateway Timeout | Métodos idempotentes apenas | Tentar com backoff |
| 400, 401, 403, 404, 405 | Não | Não tentar novamente (erro do cliente) |
Códigos de Sucesso 2xx Comuns
200 OK
A requisição foi bem-sucedida. O significado depende do método:
GET: Recurso retornado no corpo da respostaPOST: Recurso criado ou ação completadaPUT: Recurso atualizadoDELETE: Recurso deletado
201 Created
Um novo recurso foi criado. Usado principalmente com requisições POST. A resposta deve incluir um header Location apontando para o novo recurso.
204 No Content
A requisição foi bem-sucedida mas não há conteúdo para retornar. Comum para requisições DELETE ou atualizações PUT onde o cliente já tem os dados.
206 Partial Content
O servidor está entregando parte de um recurso. Usado com requisições de intervalo para arquivos grandes ou streaming de vídeo.
Códigos de Redirecionamento 3xx Comuns
301 Moved Permanently
O recurso foi movido permanentemente para uma nova URL. Clientes e motores de busca devem atualizar seus registros. O header Location contém a nova URL.
302 Found (Redirecionamento Temporário)
O recurso está temporariamente em uma URL diferente. Requisições futuras devem continuar usando a URL original.
304 Not Modified
O recurso não mudou desde a última requisição do cliente. Usado com headers condicionais como If-None-Match ou If-Modified-Since. Economiza banda ao não reenviar conteúdo inalterado.
307 Temporary Redirect / 308 Permanent Redirect
Como 302 e 301, mas preservam o método HTTP. Use 307/308 em vez de 302/301 para requisições POST ou PUT para evitar converter o método para GET.
Códigos de Erro do Cliente 4xx Comuns
400 Bad Request
O servidor não pode processar a requisição devido a erro do cliente. Causas comuns:
- JSON ou XML malformado no corpo da requisição
- Parâmetros obrigatórios ausentes
- Valores de parâmetros inválidos
- Erros de sintaxe na requisição
401 Unauthorized
Autenticação é necessária. O cliente deve se autenticar antes de acessar o recurso. A resposta deve incluir um header WWW-Authenticate indicando como autenticar.
403 Forbidden
O cliente está autenticado mas não tem permissão para acessar o recurso. Diferente de 401, reautenticar não ajuda—o cliente simplesmente não tem permissão.
404 Not Found
O recurso solicitado não existe. Pode também ser retornado em vez de 403 por segurança (para evitar confirmar que o recurso existe).
405 Method Not Allowed
O método da requisição não é suportado para este recurso. A resposta deve incluir um header Allow listando os métodos válidos.
408 Request Timeout
O servidor fechou uma conexão ociosa. O cliente deve tentar novamente em uma nova conexão.
429 Too Many Requests
O cliente excedeu os limites de taxa. Verifique o header Retry-After para quando tentar novamente.
413 Content Too Large
O corpo da requisição excede o limite configurado do servidor. O cliente deve reduzir o tamanho do payload ou usar upload fragmentado.
Códigos de Erro do Servidor 5xx Comuns
500 Internal Server Error
Um erro inesperado ocorreu no servidor. Este é um código genérico para exceções não tratadas e erros de configuração. O cliente não pode corrigir este problema.
502 Bad Gateway
Um proxy ou gateway recebeu uma resposta inválida de um servidor upstream. Comum em arquiteturas distribuídas com load balancers, CDNs ou API gateways.
503 Service Unavailable
O servidor está temporariamente incapaz de processar requisições. Causas comuns:
- Servidor sobrecarregado
- Manutenção em andamento
- Esgotamento de recursos (memória, conexões, threads)
A resposta deve incluir um header Retry-After.
504 Gateway Timeout
Um proxy ou gateway não recebeu resposta de um servidor upstream dentro do período de timeout. Diferente de 502 (resposta inválida), 504 significa que nenhuma resposta chegou.
Troubleshooting de Erros HTTP
Identifique Onde o Erro Originou-se
Em sistemas distribuídos, erros podem ocorrer em múltiplas camadas:
Cliente → CDN/Edge → Load Balancer → API Gateway → Aplicação → Banco de Dados ↑ ↑ ↑ ↑ ↑ 403/502 502/503 502/504 4xx/5xx 502/504Para encontrar a causa raiz, verifique logs em cada camada. O código de status que o cliente vê é o ÚLTIMO código gerado ao longo do caminho.
Verifique Headers para Pistas
Server: Identifica qual software gerou a respostaX-Cache-Status: Status de cache hit/miss do CDNX-Request-ID: ID de correlação para rastreamento entre serviçosRetry-After: Quando tentar novamente (429, 503)WWW-Authenticate: Requisitos de autenticação (401)
Distinga 4xx de 5xx
| Tipo de Erro | Quem Pode Corrigir | Exemplos |
|---|---|---|
| 4xx Erro do Cliente | Cliente | URL errada, auth ausente, corpo da requisição inválido |
| 5xx Erro do Servidor | Administrador do servidor | Crash do backend, sobrecarga, timeout, má configuração |
Quando Usar Cada Código de Status em Sua API
Operações Bem-sucedidas
200 OK: Sucesso padrão paraGET,PATCH201 Created: Recurso criado viaPOST202 Accepted: Requisição aceita para processamento assíncrono204 No Content: Sucesso sem corpo (DELETE, algunsPUT)
Erros do Cliente
400 Bad Request: Entrada inválida, sintaxe malformada401 Unauthorized: Autenticação ausente ou inválida403 Forbidden: Autenticado mas não autorizado404 Not Found: Recurso não existe409 Conflict: Conflito de estado (duplicata, versão incompatível)422 Unprocessable Entity: Sintaxe válida mas erros semânticos429 Too Many Requests: Limite de taxa excedido
Erros do Servidor
500 Internal Server Error: Falha inesperada do servidor502 Bad Gateway: Upstream retornou resposta inválida503 Service Unavailable: Sobrecarga temporária ou manutenção504 Gateway Timeout: Upstream não respondeu a tempo
Métricas e Medição
Acompanhe estas métricas para monitorar padrões de erro HTTP:
- Taxa de erro 5xx: Meta < 0,1% para serviços em produção
- Taxa de erro 4xx: Monitore picos indicando clientes com problemas
- Distribuição de códigos de status: Mudanças repentinas indicam problemas
- Orçamento de erro: Porcentagem de requisições falhadas permitida por SLO
Referências do mercado:
- 99,9% disponibilidade = 8,76 horas de downtime/ano
- 99,99% disponibilidade = 52,56 minutos de downtime/ano
- Principais causas de 5xx: bugs de deploy (40%), falhas de dependência (30%), mudanças de config (20%), capacidade (10%) (Google SRE)
Erros Comuns e Correções
Erro: Retornar 200 OK para erros e colocar detalhes do erro no corpo
Correção: Sempre retorne o código de status correto. Intermediários, monitoramento e clientes dependem do código numérico.
Erro: Usar 403 quando o usuário precisa se autenticar
Correção: Retorne 401 para autenticação ausente, 403 para permissões insuficientes.
Erro: Retornar 500 para erros de validação
Correção: Use 400 ou 422 para falhas de validação do lado do cliente.
Erro: Não incluir Retry-After para 429 e 503
Correção: Sempre inclua orientação de retry para prevenir tempestades de retry.
Perguntas Frequentes
Qual a diferença entre 401 e 403? 401 significa “você precisa se autenticar”. 403 significa “você está autenticado mas não tem permissão”.
Devo retornar 404 ou 403 para recursos que o usuário não pode acessar? Retorne 404 se quiser esconder a existência do recurso. Retorne 403 se o usuário deve saber que existe mas não pode acessá-lo.
Posso criar códigos de status customizados? Sim, mas devem seguir a semântica da classe (2xx para sucesso, 4xx para erros do cliente, 5xx para erros do servidor). Registre códigos customizados com IANA para APIs públicas.
Como CDNs lidam com códigos de status? CDNs fazem cache baseado no código de status e Cache-Control. A maioria das respostas 4xx e 5xx não são cacheadas por padrão.
Qual código de status webhooks devem retornar? Retorne 200 OK para confirmar recebimento. Retorne 202 Accepted para processamento assíncrono. Qualquer não-2xx acionará retries do sistema enviador.
HTTP/2 e HTTP/3 mudam códigos de status? Não. Códigos de status permanecem os mesmos entre versões HTTP.
Minha API deve retornar 500 para erros de lógica de negócio? Não. Use códigos 4xx para condições de erro esperadas. Reserve 500 para falhas técnicas inesperadas.
Qual o código correto para rate limiting? 429 Too Many Requests, com header Retry-After.