Os códigos de status HTTP são a linguagem que servidores usam para responder requisições. Entender o que cada código significa é essencial para qualquer desenvolvedor, DevOps ou designer que trabalha com APIs ou aplicações web.
Como os Códigos São Organizados
Todos os códigos HTTP têm 3 dígitos. O primeiro dígito define a categoria:
| Faixa | Categoria | Significado | |---|---|---| | 1xx | Informacional | A requisição foi recebida e está sendo processada | | 2xx | Sucesso | A requisição foi recebida, entendida e aceita | | 3xx | Redirecionamento | É preciso tomar mais ações para completar a requisição | | 4xx | Erro do cliente | A requisição contém sintaxe errada ou não pode ser atendida | | 5xx | Erro do servidor | O servidor falhou ao atender uma requisição aparentemente válida |
Códigos 1xx: Informacional
100 Continue
O servidor recebeu os cabeçalhos da requisição e o cliente pode continuar enviando o corpo.
101 Switching Protocols
O servidor aceita trocar de protocolo conforme solicitado pelo cliente (ex: HTTP → WebSocket).
102 Processing
O servidor está processando a requisição mas ainda não tem resposta disponível (WebDAV).
103 Early Hints
Permite que o cliente comece a pré-carregar recursos enquanto o servidor prepara a resposta completa.
Códigos 2xx: Sucesso
200 OK
A requisição foi bem-sucedida. O significado depende do método HTTP usado.
201 Created
A requisição foi bem-sucedida e um novo recurso foi criado como resultado. Usado em resposta a requisições POST e PUT.
202 Accepted
A requisição foi aceita mas ainda não foi processada. Comum em processamentos assíncronos.
204 No Content
A requisição foi bem-sucedida mas não há conteúdo para retornar. Comum em DELETE e PUT.
206 Partial Content
O servidor está entregando apenas parte do recurso (usado em downloads com intervalo ou streaming de vídeo).
Códigos 3xx: Redirecionamento
301 Moved Permanently
O recurso foi movido permanentemente para uma nova URL. O Google transfere PageRank para o novo endereço.
302 Found
Redirecionamento temporário. O cliente deve usar a URL original nas próximas requisições.
304 Not Modified
Indica que o recurso não mudou desde a última requisição. O cliente pode usar sua versão em cache.
307 Temporary Redirect
Igual ao 302, mas garante que o método HTTP original não será alterado.
308 Permanent Redirect
Igual ao 301, mas garante que o método HTTP original não será alterado.
Códigos 4xx: Erro do Cliente
400 Bad Request
A requisição é malformada, inválida ou não pode ser processada. Verifique o formato dos dados enviados.
401 Unauthorized
Autenticação é necessária. Na prática, significa "não autenticado": o cliente não informou credenciais válidas.
403 Forbidden
O servidor entendeu a requisição mas recusa atendê-la. O cliente está autenticado mas não tem permissão.
404 Not Found
O recurso solicitado não foi encontrado. Pode ser temporário ou permanente.
405 Method Not Allowed
O método HTTP usado (ex: DELETE) não é suportado para aquele endpoint.
408 Request Timeout
O servidor encerrou a conexão por inatividade do cliente.
409 Conflict
A requisição conflita com o estado atual do recurso (ex: tentativa de criar duplicata).
410 Gone
O recurso existiu mas foi removido permanentemente. Diferente do 404, indica remoção intencional.
413 Content Too Large
O corpo da requisição excede o limite configurado no servidor.
422 Unprocessable Content
A requisição está bem formada mas contém erros semânticos (muito usado em APIs REST para validação de dados).
429 Too Many Requests
O cliente enviou muitas requisições em pouco tempo (rate limiting).
Códigos 5xx: Erro do Servidor
500 Internal Server Error
Erro genérico do servidor. Algo deu errado que não se encaixa em nenhum outro código 5xx.
501 Not Implemented
O servidor não suporta a funcionalidade necessária para atender a requisição.
502 Bad Gateway
O servidor, atuando como gateway, recebeu uma resposta inválida do upstream.
503 Service Unavailable
O servidor está temporariamente indisponível por sobrecarga ou manutenção.
504 Gateway Timeout
O servidor, atuando como gateway, não recebeu resposta do upstream a tempo.
507 Insufficient Storage
O servidor não tem espaço suficiente para armazenar a representação necessária (WebDAV).
Dicas Práticas
Use 201 em vez de 200 ao criar recursos: retornar 201 Created com o Location header apontando para o novo recurso é a forma semânticamente correta de responder um POST bem-sucedido.
401 vs 403: 401 significa "você precisa se autenticar", 403 significa "você está autenticado mas não tem permissão". Confundir os dois é um erro clássico.
Sempre retorne 422 para erros de validação: muitas APIs ainda usam 400 para tudo, mas 422 é semanticamente mais correto quando o problema é nos dados enviados, não no formato da requisição.
Cache e 304: implementar suporte a ETag e If-None-Match permite que clientes usem o cache corretamente, reduzindo banda e latência.
Perguntas Frequentes
Qual a diferença entre 404 e 410? 404 significa "não encontrado agora"; pode ser temporário. 410 significa "foi removido de propósito e não volta". O Google trata diferente: remove o 410 do índice mais rapidamente.
Por que minha API retorna 200 mesmo quando dá erro? Padrão chamado de "200 OK with error body": muito comum em APIs antigas. É considerado má prática pois quebra o contrato do protocolo HTTP e dificulta o uso de ferramentas de monitoramento.
O código 418 existe?
Sim, 418 I'm a teapot é real. Foi definido no RFC 2324 como uma brincadeira do Dia da Mentira de 1998. Alguns servidores o implementam como easter egg.
Trabalhando com APIs? O Formatador JSON do UtilWave ajuda a visualizar e validar os corpos de requisição e resposta com um clique.