Códigos de status HTTP: como ler respostas de 1xx a 5xx

O que um código HTTP realmente informa

O código de status é a primeira resposta curta que um servidor entrega depois de receber uma requisição. Ele não conta toda a história, mas separa rapidamente sucesso, redirecionamento, problema no pedido e falha no lado do serviço. A tabela reúne os códigos que mais aparecem em navegadores, APIs, logs e ferramentas de desenvolvimento.

Leia os três dígitos como uma classe antes de procurar o caso específico: 1xx é informativo, 2xx indica sucesso, 3xx trata de redirecionamento, 4xx aponta um problema ligado à requisição e 5xx indica falha durante o atendimento pelo servidor ou por algum componente intermediário.

O status não substitui o restante da resposta

Um código é um diagnóstico inicial, não uma explicação completa. Em uma API, confira o método usado, a URL, os cabeçalhos, o corpo de erro e o horário da tentativa. Um 400 pode vir de um campo ausente; um 401 pode indicar credencial vencida; um 429 pode exigir esperar o intervalo informado pela própria plataforma.

Também não é correto esperar sempre um JSON ou uma página HTML. A RFC 9110 estabelece que respostas 1xx, 204 e 304 não incluem conteúdo. Quando uma integração recebe 204 No Content, ela pode ter sido concluída com sucesso mesmo sem um corpo para exibir.

200, 201, 202 e 204: sucessos com efeitos diferentes

O 200 confirma que a requisição foi bem-sucedida, mas não descreve sozinho qual ação aconteceu. O 201 é adequado quando um recurso foi criado. O 202 indica que o servidor aceitou o trabalho, sem prometer que o processamento já terminou. Já o 204 informa sucesso sem conteúdo adicional na resposta.

Essa diferença ajuda a evitar interfaces enganosas. Um formulário que recebe 202 precisa comunicar que a tarefa ficou pendente; uma exclusão que retorna 204 não precisa tentar interpretar um corpo inexistente. A escolha correta depende do contrato da API, não apenas da preferência por um número conhecido.

Redirecionamentos: 301, 302, 307 e 308

Códigos 3xx pedem que o cliente considere outro endereço. O 301 e o 308 são usados para mudanças permanentes; o 302 e o 307, para mudanças temporárias. A diferença prática mais importante está em 307 e 308: eles deixam explícito que o método da requisição deve ser preservado.

O 304 merece leitura separada. Ele não significa que a página quebrou nem que o servidor recusou o pedido. Em uma requisição condicional, ele informa que a representação guardada em cache continua válida; por isso a resposta não traz um novo corpo.

Como investigar um 4xx sem adivinhar

Erros 4xx geralmente apontam para algo que o cliente pode revisar. Comece conferindo caminho, método e parâmetros. Depois valide autenticação, permissão, formato do corpo e limites de uso. Essa ordem evita a troca aleatória de credenciais quando o problema real é uma URL digitada com rota errada ou um POST enviado a um recurso que aceita apenas GET.

• 401 pede autenticação válida; 403 indica recusa de acesso mesmo depois de o servidor compreender a requisição.
• 404 informa que o recurso não foi encontrado; 410 comunica que ele existiu, mas foi removido.
• 405 aponta método não aceito; 415 aponta tipo de mídia não suportado.
• 422 Unprocessable Content aparece quando a sintaxe é compreensível, mas o conteúdo não atende às regras necessárias para processá-lo.
• 429 indica que o limite de requisições foi excedido; respeite a política e os cabeçalhos da fonte antes de repetir a chamada.

Quando 5xx aponta para servidor, gateway ou dependência

Um 500 é uma falha genérica durante o processamento. Um 502 sugere que um gateway ou proxy recebeu uma resposta inválida de outro componente. Um 503 costuma apontar indisponibilidade temporária, enquanto um 504 informa que o gateway não recebeu resposta a tempo. Os quatro merecem ações diferentes, embora todos estejam na faixa de erro do servidor.

Antes de repetir a mesma chamada muitas vezes, registre o horário, o código e qualquer identificador de requisição retornado. Isso dá ao responsável pelo serviço informação concreta para investigar e evita confundir uma oscilação externa com um erro de validação da aplicação cliente.

Como usar a tabela em desenvolvimento e suporte

Pesquise pelo número quando ele aparece em um log e filtre pela classe para enxergar padrões. Se vários endpoints retornam 502 ou 504 no mesmo período, a investigação tende a seguir para proxy ou serviço de origem. Se apenas uma rota retorna 404, comece pela URL, pelo ambiente e pelo caminho publicado.

Para testar respostas reais de serviços públicos, o catálogo de APIs do DexBase oferece consultas diretas. Use a documentação de cada fonte para saber quais status ela declara no próprio contrato.

Fonte de referência e limite desta lista

Os códigos HTTP evoluem por especificação e registro. A referência normativa para a semântica geral é a RFC 9110; a IANA mantém o registro de códigos. Esta tabela destaca os casos mais recorrentes, não substitui a documentação específica de uma API ou framework.

Perguntas frequentes

204 é erro?

Não. O 204 indica que a requisição foi atendida e que não há conteúdo adicional para enviar no corpo da resposta.

Qual a diferença entre 404 e 410?

O 404 diz que o recurso não foi encontrado naquele momento. O 410 informa que ele existiu, mas foi removido de forma permanente.

502 e 504 são a mesma coisa?

Não. O 502 indica resposta inválida de um componente intermediário ou de origem; o 504 indica que o gateway esperou e não recebeu resposta a tempo.