Códigos de status HTTP explicados para desenvolvedores — o que cada código significa

Por que você precisa entender os códigos de status HTTP#

Seu site de e-commerce retorna um erro 500 durante o checkout. Os clientes veem "Algo deu errado". Mas o que deu errado de verdade? O servidor está funcionando. O banco de dados está no ar. O problema é outra coisa — mas o 500 não te diz o quê.

Seu endpoint de API retorna um erro 429, e seu app mobile dá crash em vez de mostrar uma mensagem de retry. Os usuários acham que o app está quebrado quando, na verdade, seu rate limiter está fazendo o trabalho dele.

Sua status page diz "All Systems Operational", mas os clientes relatam páginas carregando como 403 Forbidden. Seu monitoring não detectou porque só verifica a homepage.

Códigos de status HTTP são sinais. Eles te dizem o que deu errado e onde olhar. Mas só se você entender o que cada código significa.

Este guia explica todo código de status HTTP que você vai encontrar, o que dispara cada um e o que fazer quando ver um.

---

Códigos de status HTTP: o panorama completo#

As respostas HTTP são organizadas em cinco classes:

• 1xx (100-199): Informativo — "Requisição recebida, processando"
• 2xx (200-299): Sucesso — "Tudo funcionou"
• 3xx (300-399): Redirecionamento — "Tente em outro lugar"
• 4xx (400-499): Client Error — "Você fez besteira"
• 5xx (500-599): Server Error — "Nós fizemos besteira"

Cada classe te diz onde está o problema. Se você está recebendo erros 4xx, o problema está na requisição (URL errada, autenticação errada, dados faltando). Se está recebendo erros 5xx, o problema está no seu servidor.

---

Códigos de sucesso 2xx (Tudo deu certo)#

200 OK#

O que significa: A requisição teve sucesso. O body da resposta contém os dados solicitados.

Quando você vê:

• Navegador carrega uma página web
• API retorna dados JSON
• Envio de formulário tem sucesso

Exemplo:

GET /api/users/123
Response: 200 OK
Body: {"id": 123, "name": "John", "email": "john@example.com"}

Ação: Nenhuma. Tudo está funcionando corretamente.

201 Created#

O que significa: A requisição teve sucesso e um novo recurso foi criado. A resposta inclui o recurso recém-criado.

Quando você vê:

• POST para criar um novo usuário retorna 201 Created
• Criar um novo pedido retorna 201 Created
• Fazer upload de um arquivo retorna 201 Created

Exemplo:

POST /api/users
Request: {"name": "Jane", "email": "jane@example.com"}
Response: 201 Created
Body: {"id": 456, "name": "Jane", "email": "jane@example.com", "created_at": "2026-02-20T10:00:00Z"}

Ação: Nenhuma. O recurso foi criado com sucesso.

202 Accepted#

O que significa: A requisição foi aceita para processamento, mas ainda não foi processada. Usado para operações assíncronas.

Quando você vê:

• Envio de um job demorado (ex.: codificação de vídeo, geração de relatório)
• Operações de processamento em batch
• Tarefas que serão processadas em background

Exemplo:

POST /api/batch-emails/send
Request: {"recipient_ids": [1,2,3,...,10000]}
Response: 202 Accepted
Body: {"job_id": "job_12345", "status": "queued"}

Ação: A tarefa está na fila. Volte depois usando o job ID para ver o status.

204 No Content#

O que significa: A requisição teve sucesso, mas não há conteúdo para retornar.

Quando você vê:

• Requisições DELETE (deletado com sucesso, nada para retornar)
• PATCH bem-sucedido sem body de resposta
• Confirmações de webhook

Exemplo:

DELETE /api/users/123
Response: 204 No Content
Body: (vazio)

Ação: Nenhuma. A ação teve sucesso.

---

Códigos de redirecionamento 3xx (Tente em outro lugar)#

301 Moved Permanently#

O que significa: O recurso foi movido permanentemente para uma nova URL. Os mecanismos de busca atualizam o índice e os navegadores passam a usar a nova URL para requisições futuras.

Quando você vê:

• Site migrado de www.oldsite.com para newsite.com
• Endpoint de API antigo substituído por um novo
• Estrutura de URL alterada

Exemplo:

GET /old-page.html
Response: 301 Moved Permanently
Header: Location: /new-page.html

Ação:

• Para usuários: o navegador segue o redirecionamento automaticamente (transparente)
• Para SEO: garanta que o 301 seja usado para mudanças permanentes (o Google transfere o page rank)
• Para APIs: os clientes devem atualizar para a nova URL

302 Found (Redirecionamento temporário)#

O que significa: O recurso foi temporariamente movido para outra URL. A URL original ainda é válida, então os navegadores NÃO fazem cache da nova URL.

Quando você vê:

• Redirecionamentos temporários durante manutenção
• Redirecionamentos para a página de login
• Testes A/B (redirecionar parte dos usuários para a nova versão temporariamente)

Exemplo:

GET /products/discount-flash-sale
Response: 302 Found
Header: Location: /products/2026-flash-sale

Ação: O navegador segue o redirecionamento temporariamente, mas continua tratando a URL original como principal.

304 Not Modified#

O que significa: O recurso não mudou desde sua última requisição. Use a versão em cache.

Quando você vê:

• O navegador verifica se a página mudou desde a última visita (checa data de modificação/ETag)
• A API retorna 304 se os dados não mudaram desde a última requisição
• Reduz banda evitando reenviar dados que não mudaram

Exemplo:

GET /api/user-profile
Request Header: If-Modified-Since: 2026-02-19 10:00:00
Response: 304 Not Modified
Body: (vazio — use a versão anterior em cache)

Ação: O navegador/cliente usa a versão em cache localmente.

307 Temporary Redirect#

O que significa: Como o 302, mas garante que o método HTTP permaneça o mesmo durante o redirecionamento.

Diferença técnica:

• 302 permite mudança de método (POST → GET após redirecionamento)
• 307 preserva o método (POST → POST após redirecionamento)

Quando você vê:

• Envio de formulário redireciona para a página de confirmação (POST → POST)
• Redirecionamentos de API que precisam preservar o método

Por que importa: Navegadores antigos às vezes convertiam redirecionamentos POST em GET, o que podia perder dados do formulário. O 307 evita isso.

---

Códigos de erro do cliente 4xx (Você fez besteira)#

400 Bad Request#

O que significa: A requisição estava mal formada. O servidor não conseguiu entender.

Quando você vê:

• JSON mal formado no body da requisição
• Campos obrigatórios faltando
• Formato de parâmetro inválido
• Erro de sintaxe na query string

Exemplo:

POST /api/users
Request Body: {"name": "Jane" "email": "jane@example.com"}
                              ↑ Vírgula faltando
Response: 400 Bad Request
Body: {"error": "Invalid JSON syntax"}

Ação:

• Verifique a formatação da requisição
• Valide a sintaxe do JSON
• Garanta que os campos obrigatórios estejam presentes
• Confira se os tipos de parâmetro batem com a documentação da API

401 Unauthorized#

O que significa: A autenticação falhou ou está faltando. Você não provou quem é.

Quando você vê:

• Nenhum token de autenticação enviado
• Token de autenticação inválido ou expirado
• Usuário/senha errados
• API key faltando

Exemplo:

GET /api/user-profile
(Sem header Authorization)
Response: 401 Unauthorized
Body: {"error": "Authentication required"}

Ação:

• Forneça autenticação válida (login, API key, token, etc.)
• Renove tokens expirados
• Verifique se as credenciais estão corretas

403 Forbidden#

O que significa: A autenticação funcionou, mas você não tem permissão para acessar este recurso.

Quando você vê:

• Usuário tenta deletar a conta de outro usuário
• Usuário tenta acessar um endpoint exclusivo de admin
• Usuário tenta acessar um recurso de outra organização
• Permissões/role insuficientes

Exemplo:

DELETE /api/users/999
(Autenticado como user 123, tentando deletar user 999)
Response: 403 Forbidden
Body: {"error": "You can only delete your own account"}

Ação:

• Use a conta correta com as permissões adequadas
• Solicite permissões elevadas, se necessário
• Verifique se está acessando o recurso certo

404 Not Found#

O que significa: O recurso não existe ou o servidor não tem ideia de como tratar este endpoint.

Quando você vê:

• Erro de digitação na URL (/users/ vs /users)
• Endpoint não existe
• Recurso deletado
• Versão de API errada

Exemplo:

GET /api/users/nonexistent-id-12345
Response: 404 Not Found
Body: {"error": "User not found"}

Ação:

• Verifique a grafia da URL
• Confirme que o endpoint existe
• Consulte a documentação da API
• Tente um ID/recurso diferente

405 Method Not Allowed#

O que significa: O endpoint existe, mas não suporta este método HTTP.

Quando você vê:

• Usar POST em um endpoint que só aceita GET
• Usar DELETE em um endpoint que não suporta deleção
• Usar PATCH quando só PUT é permitido

Exemplo:

DELETE /api/domains/123
(Se DELETE não é suportado no endpoint domains)
Response: 405 Method Not Allowed
Header: Allow: GET, POST, PUT

Ação: Use o método HTTP correto. A resposta normalmente inclui o header Allow mostrando os métodos válidos.

408 Request Timeout#

O que significa: O servidor esperou tempo demais o cliente enviar a requisição e desistiu.

Quando você vê:

• Cliente lento fazendo upload de arquivo grande
• Conexão de rede cai no meio da requisição
• A requisição leva mais que o timeout do servidor (geralmente 30-300 segundos)

Exemplo:

POST /api/upload
(Upload de arquivo de 500MB em conexão lenta leva 10 minutos)
Response: 408 Request Timeout

Ação:

• Tente a requisição novamente
• Divida requisições grandes em pedaços menores
• Verifique a conexão de rede
• Aumente o timeout do cliente, se for o caso

429 Too Many Requests#

O que significa: Você está fazendo requisições demais. O rate limit foi excedido.

Quando você vê:

• Atingindo o rate limit da API (ex.: 100 requisições/minuto)
• Enviando e-mails rápido demais
• Tentativas de login por força bruta
• Web scraper batendo no servidor com força demais

Exemplo:

GET /api/users/123
(100ª requisição no último minuto)
Response: 429 Too Many Requests
Header: Retry-After: 60
Body: {"error": "Rate limit exceeded. Try again in 60 seconds"}

Ação:

• Aguarde antes de tentar de novo (verifique o header Retry-After)
• Implemente exponential backoff
• Use paginação para grandes conjuntos de resultados
• Faça cache dos resultados localmente em vez de requisitar de novo

---

Códigos de erro do servidor 5xx (Nós fizemos besteira)#

500 Internal Server Error#

O que significa: Algo deu errado no servidor, e ele não consegue dar mais detalhes.

Quando você vê:

• Exceção não tratada no código
• Falha de conexão com o banco de dados
• Sem memória
• Condição inesperada

Exemplo:

POST /api/checkout
Response: 500 Internal Server Error
Body: {"error": "Something went wrong"}

Por que é vago: Servidores não expõem detalhes internos de erro para clientes por motivos de segurança. Erros detalhados ajudam atacantes.

Ação:

• Confira os logs do servidor para ver o erro real
• Se for um serviço de terceiros: contate o suporte
• Se for seu serviço: confira os logs de erro, reinicie se necessário, faça rollback do deploy recente

501 Not Implemented#

O que significa: O servidor não suporta este método HTTP ou recurso.

Quando você vê:

• Servidor não suporta funcionalidades de HTTP/2
• WebSocket não suportado
• Certos métodos HTTP não implementados

Exemplo:

OPTIONS /api/users
(Servidor não suporta o método OPTIONS)
Response: 501 Not Implemented

Ação: Geralmente nada — use um método ou serviço diferente. Raro em APIs modernas.

502 Bad Gateway#

O que significa: O servidor recebeu uma resposta inválida de um servidor upstream.

Cenários reais:

1. Reverse proxy (Nginx) não consegue conectar no backend

   Client → Nginx (gateway) → Node.js Backend
                   ↑
            Backend está fora ou não responde
   

2. Load balancer não consegue alcançar nenhum backend saudável

   Client → Load Balancer → Backend Servers
                         ↑
              Todos os backends fora ou lentos
   

3. API Gateway não consegue alcançar microsserviço

   Client → API Gateway → Auth Service (fora)
                       → User Service
                       → Order Service
   

Por que acontece:

• Servidor backend caiu
• Conectividade de rede perdida
• Servidor upstream lento e dá timeout
• Upstream retorna resposta mal formada

Exemplo:

GET /dashboard
Response: 502 Bad Gateway

Por trás dos panos:

Nginx recebeu a requisição
Tentou encaminhar para o Node.js em localhost:3000
Conexão recusada (servidor não está rodando)
Nginx retornou: 502 Bad Gateway

Ação:

• Verifique se os serviços de backend estão rodando: docker ps, pm2 status, status do systemd
• Confira a conectividade de rede até o backend
• Veja os logs do backend em busca de crashes
• Reinicie o serviço de backend se ele caiu
• Verifique se o load balancer está roteando corretamente

503 Service Unavailable#

O que significa: O servidor está temporariamente incapaz de atender requisições (manutenção, sobrecarga, dependências fora do ar).

Quando você vê:

• Servidor está reiniciando
• Servidor está sob carga pesada (todas as conexões em uso)
• Banco de dados está fora ou em migração
• Dependência de terceiro está fora
• Deploy em andamento (tráfego está pausado)

Exemplo:

GET /api/users
Response: 503 Service Unavailable
Header: Retry-After: 600
Body: {"error": "Server is undergoing maintenance. Try again in 10 minutes"}

Por que servidores retornam 503 durante manutenção:

• Diz aos clientes "isso é temporário, tente de novo depois"
• Navegadores e clientes sabem que devem tentar novamente automaticamente
• Mecanismos de busca não penalizam o 503 (diferente do 500, que parece um bug)

Ação:

• Aguarde e tente novamente (veja o header Retry-After para saber por quanto tempo)
• Confira a status page para ver janelas de manutenção
• Se for serviço interno: aguarde o deploy terminar, confira os logs

504 Gateway Timeout#

O que significa: O servidor não recebeu resposta do servidor upstream a tempo.

Quando você vê:

• Servidor backend está lento demais
• Latência de rede alta demais
• Query no banco de dados levando muito tempo
• Servidor upstream travado

Exemplo:

Requisição backend:
GET /api/heavy-report
Aguardando 30 segundos...
Timeout!
Response: 504 Gateway Timeout

Causa real:

Client → Nginx (timeout 30s) → Node.js Backend (query de 60s)
                             ↑
              Nginx desiste após 30s
              Backend ainda está rodando a query

Ação:

• Verifique a performance do backend
• Procure queries lentas no banco
• Otimize o código
• Adicione índices no banco
• Aumente o timeout se a operação realmente levar mais
• Quebre operações longas em jobs assíncronos

---

Tabela de referência de códigos de status HTTP#

Código	Nome	Categoria	Significado
200	OK	Sucesso	Requisição teve sucesso
201	Created	Sucesso	Recurso criado
202	Accepted	Sucesso	Requisição enfileirada para processamento
204	No Content	Sucesso	Sucesso, sem body de resposta
301	Moved Permanently	Redirecionamento	Use a nova URL permanentemente
302	Found	Redirecionamento	Temporariamente em outra URL
304	Not Modified	Redirecionamento	Use a versão em cache
307	Temp Redirect	Redirecionamento	Preserva o método HTTP no redirecionamento
400	Bad Request	Erro do cliente	Requisição mal formada
401	Unauthorized	Erro do cliente	Autenticação obrigatória
403	Forbidden	Erro do cliente	Acesso negado
404	Not Found	Erro do cliente	Recurso não existe
405	Method Not Allowed	Erro do cliente	Método HTTP errado
408	Request Timeout	Erro do cliente	Requisição demorou demais
429	Too Many Requests	Erro do cliente	Rate limit aplicado
500	Internal Server Error	Erro do servidor	Erro genérico do servidor
501	Not Implemented	Erro do servidor	Recurso não suportado
502	Bad Gateway	Erro do servidor	Erro do servidor upstream
503	Service Unavailable	Erro do servidor	Servidor temporariamente fora
504	Gateway Timeout	Erro do servidor	Upstream lento demais

---

Como debugar problemas de códigos de status HTTP#

Passo 1: Identifique o código de status#

No navegador:

1. Abra o DevTools (F12)
2. Vá para a aba Network
3. Olhe a requisição que falhou
4. A coluna Status mostra o código

No terminal:

curl -i https://example.com/endpoint
# Primeira linha mostra: HTTP/1.1 200 OK

Na aplicação:

• Confira os logs de erro
• Veja o objeto de resposta
• A maioria dos frameworks expõe o código de status

Passo 2: Entenda o que ele significa#

Use as categorias:

• 2xx? Funcionando como esperado
• 3xx? Verifique o destino do redirecionamento
• 4xx? Verifique o formato da requisição e as permissões
• 5xx? Verifique os logs do servidor e as dependências upstream

Passo 3: Olhe o body e os headers da resposta#

Body da resposta: A maioria das APIs inclui detalhes do erro:

{
  "error": "User not found",
  "message": "No user with ID 12345",
  "code": "USER_NOT_FOUND"
}

Headers da resposta: Os mais importantes:

• Retry-After — Por quanto tempo esperar antes de tentar de novo (429, 503)
• Allow — Métodos HTTP válidos (405)
• Location — Para onde redirecionar (3xx)
• WWW-Authenticate — Como autenticar (401)

Passo 4: Tome a ação certa com base na classe do código#

Erro de cliente 4xx:

• Você enviou dados errados? Corrija a requisição
• Tem erro de digitação na URL? Conserte
• Não tem permissão? Solicite acesso
• Endpoint errado? Consulte a documentação

Erro de servidor 5xx:

• O servidor está rodando? Verifique o uptime
• Os logs mostram erros? Corrija o erro
• Upstream está fora? Aguarde a recuperação
• Foi feito deploy recente? Faça rollback se preciso

---

Exemplo real: debugando um 502 Bad Gateway#

Cenário:

GET /api/checkout
Response: 502 Bad Gateway
Clientes não conseguem finalizar compras

Passo 1: Confirme que é um 502 ✓ O header da resposta mostra HTTP/1.1 502 Bad Gateway

Passo 2: Confira o que o 502 significa ✓ O servidor upstream não está respondendo corretamente

Passo 3: Diagnostique o problema

Os serviços de backend estão rodando?

docker ps
# Output: checkout-service is not running

✗ O serviço de checkout caiu

Passo 4: Encontre a causa raiz

Confira os logs:

docker logs checkout-service
# Out of memory error!
# Java heap space exhausted

Passo 5: Conserte

Aumente a memória:

docker-compose up -d --build

Ou reinicie:

docker restart checkout-service

Passo 6: Verifique

curl -i https://api.example.com/api/checkout
# HTTP/1.1 200 OK ✓

---

Monitorando códigos de status em tempo real#

Por que você deve monitorar#

• Detectar downtime antes dos clientes reportarem
• Pegar erros 5xx que afetam só certos endpoints
• Acompanhar erros 4xx para encontrar uso indevido da API
• Monitorar o rate limit 429 para saber a hora de escalar

O que monitorar#

Crítico (acionar plantão se cair):

• Qualquer erro 5xx em endpoints críticos (checkout, login, pagamento)

Importante (investigar):

• Pico de erros 429 (rate limiting indica que você está perto do limite de capacidade)
• Erros 502/504 aumentando (degradação upstream)
• Aumento de erros 403/401 (possível ataque de força bruta)

Informativo (acompanhar tendências):

• Erros 404 (URLs erradas sendo requisitadas?)
• Erros 400 (clientes mandando requisições mal formadas?)

Usando o Nova Uptime para monitorar códigos de status#

O monitoring de uptime do Nova Uptime acompanha códigos de status HTTP em tempo real:

1. Monitores retornam 200? Site no ar ✓
2. Monitores retornam 404? URL errada ou endpoint deletado ✗
3. Monitores retornam 429? Você está sendo rate-limited ⚠️
4. Monitores retornam 502/503? Problema no backend ✗
5. Monitores retornam 504? Timeout, precisa de otimização ⚠️

O Nova Uptime te mostra:

• Quais códigos de status estão sendo retornados
• Quando começaram a ocorrer
• Quais endpoints estão afetados
• Tendência ao longo do tempo

---

Códigos de status HTTP e SEO#

Os mecanismos de busca usam códigos de status para decidir como indexar as páginas:

200 OK: Indexa esta página (normal)

301 Moved Permanently: Atualiza o índice para apontar para a nova URL

302 Found: Mantém a URL antiga no índice, não segue o redirecionamento

304 Not Modified: Não recrawla, a última versão é a atual

401/403: Não indexa (acesso negado)

404 Not Found: Remove do índice (página sumiu)

410 Gone: Remove do índice (página sumiu, não vai voltar)

429/503/504: Tenta de novo depois (problema temporário)

Erros 5xx: Possível problema no site; o Google reduz o ritmo do crawl

Importante para a saúde do site:

• Use 301 para mudanças permanentes de URL (preserva o valor de SEO)
• Use 410 para dizer explicitamente ao Google que uma página foi embora
• Corrija erros 5xx rápido (o Google despriorizar sites quebrados)
• Implemente robots.txt para evitar 404 em conteúdo não indexável

---

Resumo: referência rápida de códigos de status HTTP#

Está tudo bem:

• 200 OK — Sucesso normal
• 201 Created — Novo recurso criado
• 204 No Content — Sucesso, sem resposta necessária

Redireciona para outro lugar:

• 301/302 — Siga o redirecionamento para a nova URL
• 304 — Use a versão em cache

Você cometeu um erro:

• 400 Bad Request — Conserte a formatação da requisição
• 401 Unauthorized — Forneça autenticação
• 403 Forbidden — Você não tem permissão
• 404 Not Found — URL errada
• 429 Too Many Requests — Diminui o ritmo, você está sendo rate-limited

Nós cometemos um erro:

• 500 Internal Server Error — Confira os logs do servidor
• 502 Bad Gateway — Serviço de backend está fora
• 503 Service Unavailable — Servidor temporariamente fora
• 504 Gateway Timeout — Backend está lento demais

Monitorando com o Nova Uptime: O monitoring HTTP do Nova Uptime detecta esses erros instantaneamente e te avisa antes dos clientes notarem. Monitore endpoints críticos, acompanhe tendências de códigos de status e receba alertas quando os erros 5xx dispararem.

---

Última atualização: 20 de fevereiro de 2026 O Nova Uptime monitora códigos de status HTTP em mais de 50 tipos de checagem e alerta sobre erros 5xx em tempo real