O Guia Definitivo dos Códigos de Status HTTP
Os códigos de status HTTP indicam o resultado do processamento de uma requisição por um servidor web. Eles são agrupados em cinco classes, cada uma representando uma categoria diferente de resposta. Entender esses códigos é essencial para desenvolvedores web, designers de API, administradores de sistemas e qualquer pessoa que trabalhe com tecnologias web. Os códigos de status permitem que clientes — sejam navegadores, aplicativos móveis ou outros servidores — entendam o que aconteceu com sua requisição e como proceder.
Como Funcionam os Códigos de Status HTTP
Quando um cliente envia uma requisição HTTP para um servidor, o servidor responde com um código de status de três dígitos seguido por uma frase de motivo legível. O primeiro dígito do código de status define a classe da resposta. Os dois dígitos restantes não têm nenhum papel de categorização específico, mas fornecem granularidade dentro de cada classe. Os códigos de status são definidos pela Internet Assigned Numbers Authority (IANA) com base em especificações publicadas em documentos RFC. Em 2025, existem mais de 70 códigos de status HTTP oficialmente registrados, embora apenas cerca de 30-40 estejam em uso comum.
Referência Rápida
| Classe | Categoria | Significado |
|---|---|---|
| 1xx | Informativo | Requisição recebida, continuando processamento |
| 2xx | Sucesso | Requisição recebida, compreendida e aceita |
| 3xx | Redirecionamento | Ação adicional necessária para completar a requisição |
| 4xx | Erro do Cliente | Requisição tem sintaxe inválida ou não pode ser atendida |
| 5xx | Erro do Servidor | Servidor falhou ao atender uma requisição válida |
1xx - Informativo
Estes códigos indicam que o servidor recebeu os cabeçalhos da requisição e o cliente deve continuar enviando o corpo, ou que o servidor está mudando para um protocolo diferente. Estas são respostas provisórias sem conteúdo de corpo real.
| Código | Nome | Descrição |
|---|---|---|
| 100 | Continue | Servidor recebeu cabeçalhos, cliente deve continuar enviando corpo |
| 101 | Switching Protocols | Servidor está mudando de protocolo (ex.: atualizando para WebSocket) |
| 102 | Processing | Servidor está processando a requisição mas ainda sem resposta (WebDAV) |
| 103 | Early Hints | Pré-carregar recursos enquanto servidor prepara resposta, usado para otimização de desempenho |
O status 100 Continue é frequentemente usado em conjunto com o cabeçalho de requisição Expect: 100-continue. Quando um cliente envia este cabeçalho, ele aguarda confirmação antes de enviar um payload grande. Isso evita desperdício de largura de banda quando o servidor vai rejeitar a requisição com base apenas nos cabeçalhos.
101 Switching Protocols é a base das conexões WebSocket. Quando um cliente envia um cabeçalho Upgrade: websocket, o servidor responde com 101 para confirmar a mudança de protocolo de HTTP para WebSocket, permitindo comunicação bidirecional em tempo real.
103 Early Hints é uma adição relativamente nova (RFC 8297) que permite que servidores enviem dicas ao navegador sobre recursos críticos (CSS, JavaScript, fontes) que serão necessários pela resposta final. Isso permite que o navegador comece a pré-carregar estes recursos antes que a resposta completa esteja pronta, melhorando o desempenho percebido.
2xx - Sucesso
Estes códigos indicam que a requisição do cliente foi recebida, compreendida e aceita com sucesso. Esta é a categoria que todo desenvolvedor espera ver.
| Código | Nome | Descrição |
|---|---|---|
| 200 | OK | Resposta de sucesso padrão para requisições GET, POST, PUT |
| 201 | Created | Recurso criado com sucesso, tipicamente em resposta a POST |
| 202 | Accepted | Requisição aceita para processamento mas ainda não concluída |
| 203 | Non-Authoritative Info | Resposta de uma fonte terceira, não do servidor de origem |
| 204 | No Content | Sucesso, mas sem corpo de resposta para retornar |
| 205 | Reset Content | Diz ao navegador para limpar o formulário/documento atual |
| 206 | Partial Content | Recurso parcial retornado, usado para requisições de intervalo e downloads retomáveis |
| 207 | Multi-Status | Múltiplos códigos de status para múltiplos recursos (WebDAV) |
| 208 | Already Reported | Recurso já foi reportado (WebDAV) |
200 OK é o código de status mais comum. Indica que a requisição foi bem-sucedida e o corpo da resposta contém os dados solicitados. Para requisições GET, o corpo contém a representação do recurso. Para requisições POST, contém o resultado da ação.
201 Created deve ser retornado quando um novo recurso é criado como resultado de uma requisição POST ou PUT. A resposta deve incluir um cabeçalho Location apontando para a URL do recurso recém-criado. Por exemplo, após criar um novo usuário, retorne 201 Created com a URL do perfil do usuário no cabeçalho Location.
204 No Content é útil para requisições DELETE ou atualizações PUT onde o corpo da resposta está vazio. Informa ao cliente que a operação foi bem-sucedida, mas não há nada para retornar. O navegador não deve alterar sua visualização atual do documento.
3xx - Redirecionamento
Estes códigos indicam que o cliente precisa tomar uma ação adicional para completar a requisição, geralmente seguindo um redirecionamento para uma URL diferente.
| Código | Nome | Descrição |
|---|---|---|
| 300 | Multiple Choices | Múltiplas representações possíveis, cliente deve escolher |
| 301 | Moved Permanently | Recurso tem uma nova URL permanente, atualizar favoritos |
| 302 | Found | Redirecionamento temporário, continuar usando URL original no futuro |
| 303 | See Other | Redirecionar para uma URL diferente usando método GET |
| 304 | Not Modified | Recurso não modificado, usar versão em cache |
| 307 | Temporary Redirect | Redirecionamento temporário preservando método HTTP |
| 308 | Permanent Redirect | Redirecionamento permanente preservando método HTTP |
A distinção entre 301 e 302 é crítica para SEO. Motores de busca tratam redirecionamentos 301 como permanentes, transferindo o poder de classificação da URL original para a nova URL. Um redirecionamento 302 não transfere valor de SEO porque a URL original deve retornar.
304 Not Modified é usado em conjunto com cabeçalhos de requisição condicionais como If-Modified-Since ou If-None-Match (ETags). Quando o cliente tem uma versão em cache de um recurso, ele pode perguntar ao servidor se o recurso mudou. Se não mudou, o servidor retorna 304 sem corpo, economizando largura de banda em ambos os lados.
307 e 308 preservam o método HTTP usado na requisição original, ao contrário de 302 e 301 que podem mudar POST para GET. Esta distinção é importante para endpoints de API onde preservar o método da requisição é relevante.
4xx - Erro do Cliente
Estes códigos indicam que o cliente enviou uma requisição problemática. O erro está do lado do cliente — o servidor está funcionando corretamente.
| Código | Nome | Descrição |
|---|---|---|
| 400 | Bad Request | Sintaxe ou parâmetros de requisição inválidos |
| 401 | Unauthorized | Autenticação é necessária ou falhou |
| 402 | Payment Required | Reservado para uso futuro, raramente implementado |
| 403 | Forbidden | Cliente autenticado mas não tem permissão |
| 404 | Not Found | O recurso solicitado não existe |
| 405 | Method Not Allowed | O método HTTP não é suportado para esta URL |
| 406 | Not Acceptable | Não é possível gerar resposta que corresponda aos cabeçalhos Accept |
| 407 | Proxy Authentication | Deve autenticar com um proxy primeiro |
| 408 | Request Timeout | Servidor excedeu o tempo limite aguardando a requisição |
| 409 | Conflict | Requisição conflita com o estado atual do servidor |
| 410 | Gone | Recurso permanentemente deletado, sem endereço de encaminhamento |
| 411 | Length Required | Cabeçalho Content-Length é necessário |
| 412 | Precondition Failed | Cabeçalhos de requisição condicional avaliaram como falso |
| 413 | Payload Too Large | Corpo da requisição excede limites do servidor |
| 414 | URI Too Long | URL excede o comprimento máximo permitido pelo servidor |
| 415 | Unsupported Media Type | Content-Type não suportado pelo servidor |
| 416 | Range Not Satisfiable | Cabeçalho Range não pode ser satisfeito |
| 417 | Expectation Failed | Cabeçalho Expect não pode ser satisfeito |
| 422 | Unprocessable Entity | Corpo da requisição está sintaticamente correto mas semanticamente inválido |
| 423 | Locked | Recurso está bloqueado (WebDAV) |
| 424 | Failed Dependency | Requisição falhou porque outra requisição falhou (WebDAV) |
| 426 | Upgrade Required | Cliente deve mudar para um protocolo diferente |
| 428 | Precondition Required | Servidor de origem exige que a requisição seja condicional |
| 429 | Too Many Requests | Cliente excedeu limites de taxa |
| 431 | Request Header Too Large | Cabeçalhos excedem tamanho máximo |
| 451 | Unavailable For Legal Reasons | Recurso bloqueado devido a exigências legais |
400 Bad Request é o curinga para erros do cliente. Use-o quando o servidor não puder processar a requisição devido a sintaxe malformada, parâmetros de consulta inválidos ou um corpo de requisição malformado. Sempre inclua uma mensagem de erro descritiva no corpo da resposta para ajudar os clientes a corrigir o problema.
401 Unauthorized é retornado quando o cliente não forneceu credenciais de autenticação válidas. A resposta deve incluir um cabeçalho WWW-Authenticate indicando o esquema de autenticação (Basic, Bearer, Digest, etc.) que o servidor espera.
403 Forbidden difere de 401 porque o cliente está autenticado mas não tem permissões suficientes. Por exemplo, um usuário comum tentando acessar um endpoint de administrador deve receber 403, não 401.
404 Not Found é o código de status HTTP mais conhecido. Indica que o servidor não pode encontrar o recurso solicitado. Cuidado para não revelar se o recurso existe mas está oculto — retornar 404 tanto para recursos inexistentes quanto para recursos proibidos é uma prática de segurança comum.
409 Conflict é útil para APIs REST quando há um conflito de versão. Por exemplo, quando uma requisição PUT atualiza um recurso que foi modificado por outro usuário desde que o cliente o buscou pela última vez.
429 Too Many Requests é essencial para limitação de taxa de API. Deve incluir um cabeçalho Retry-After indicando quanto tempo o cliente deve aguardar antes de fazer outra requisição.
5xx - Erro do Servidor
Estes códigos indicam que o servidor encontrou um erro ao processar uma requisição válida. O problema está do lado do servidor.
| Código | Nome | Descrição |
|---|---|---|
| 500 | Internal Server Error | Erro genérico do servidor, sem detalhes específicos disponíveis |
| 501 | Not Implemented | Servidor não suporta a funcionalidade solicitada |
| 502 | Bad Gateway | Servidor upstream retornou uma resposta inválida |
| 503 | Service Unavailable | Servidor temporariamente indisponível (sobrecarregado ou inativo) |
| 504 | Gateway Timeout | Servidor upstream não respondeu a tempo |
| 505 | HTTP Version Not Supported | Servidor não suporta a versão do protocolo HTTP usada |
| 506 | Variant Also Negotiates | Erro de configuração do servidor na negociação de conteúdo |
| 507 | Insufficient Storage | Servidor não pode armazenar a representação (WebDAV) |
| 508 | Loop Detected | Servidor detectou um loop infinito (WebDAV) |
| 509 | Bandwidth Limit Exceeded | Não é um status oficial, usado por alguns módulos Apache |
| 510 | Not Extended | Extensões adicionais são necessárias para a requisição |
| 511 | Network Authentication Required | Cliente deve autenticar para acessar a rede |
500 Internal Server Error é o curinga para falhas do lado do servidor. Nunca deve ser retornado para requisições de cliente inválidas — essas devem usar códigos 4xx. Uma resposta 500 indica que algo deu errado na lógica de processamento do servidor.
502 Bad Gateway tipicamente ocorre quando um proxy ou balanceador de carga recebe uma resposta inválida de um servidor upstream. Por exemplo, se um servidor de aplicação falhar ou retornar uma resposta malformada, o proxy reverso retorna 502 para o cliente.
503 Service Unavailable é usado quando o servidor está temporariamente sobrecarregado ou inativo para manutenção. Inclua um cabeçalho Retry-After para que clientes e rastreadores saibam quando tentar novamente. Isso é comumente visto durante janelas de implantação ou picos de tráfego.
504 Gateway Timeout ocorre quando um servidor em uma cadeia (ex.: um proxy reverso conversando com um servidor de aplicação) não recebe uma resposta oportuna de outro servidor. O tempo limite padrão é tipicamente de 30 a 120 segundos, dependendo da infraestrutura.
Guia de Uso de Códigos de Status
| Cenário | Código de Status |
|---|---|
| Requisição GET bem-sucedida | 200 |
| POST bem-sucedido (criado) | 201 |
| DELETE bem-sucedido | 204 |
| Validação de formulário falha | 422 |
| Usuário não autenticado | 401 |
| Usuário sem permissão | 403 |
| Recurso não encontrado | 404 |
| Limite de taxa excedido | 429 |
| Falha no servidor | 500 |
| Endpoint de API ainda não implementado | 501 |
| Manutenção temporária | 503 |
Melhores Práticas para Usar Códigos de Status HTTP
Sempre use o código de status mais específico que se aplica à sua situação. Retornar um erro genérico 500 quando um 503 ou 504 é mais apropriado dificulta a depuração para consumidores de API. Inclua mensagens de erro descritivas e identificadores de erro únicos em seus corpos de resposta para ajudar na depuração. Para APIs REST, considere também incluir um código de erro legível por máquina que os clientes possam processar programaticamente. Finalmente, garanta que suas respostas de erro respeitem o tipo de conteúdo solicitado através da negociação de conteúdo — retorne JSON para clientes de API e HTML para páginas de erro baseadas em navegador.
Use a ferramenta Referência de Códigos de Status HTTP para consultas rápidas sempre que precisar recordar o significado ou uso adequado de qualquer código de status HTTP.
