Códigos HTTP
Referência pesquisável de status HTTP com orientação prática para APIs.
68 códigos
- 100
Continue
O servidor recebeu os cabeçalhos e o cliente pode enviar o corpo da requisição.
Quando usar: Resposta a "Expect: 100-continue" antes de uploads grandes. Quase sempre tratada pelo servidor HTTP, não pela aplicação.
- 101
Switching Protocols
O servidor aceitou trocar de protocolo, como na atualização para WebSocket.
Quando usar: Use no handshake de WebSocket (Upgrade: websocket). Depois dele a conexão deixa de falar HTTP.
- 102
Processing
O servidor ainda está processando uma requisição WebDAV demorada. Está obsoleto.
Quando usar: Evite em APIs novas. Para trabalho demorado, responda 202 e ofereça uma URL para consultar o andamento.
- 103
Early Hints
Permite enviar cabeçalhos Link antes da resposta final para o navegador começar a carregar recursos.
Quando usar: Útil em CDNs e servidores web para acelerar páginas. Não é usado em APIs JSON.
- 200
OK
A requisição deu certo. O significado do corpo depende do método.
Quando usar: Resposta padrão para GET, PUT e PATCH bem-sucedidos que devolvem conteúdo. Se não há corpo, prefira 204.
- 201
Created
Um novo recurso foi criado como resultado da requisição.
Quando usar: Devolva em POST que cria algo, com o cabeçalho Location apontando para o novo recurso e, de preferência, sua representação.
- 202
Accepted
A requisição foi aceita, mas o processamento ainda não terminou.
Quando usar: Para trabalho assíncrono: devolva 202 com uma URL de status (Location) para o cliente consultar o resultado.
- 203
Non-Authoritative Information
O conteúdo veio de um intermediário (proxy) que modificou a resposta original.
Quando usar: Raro. Normalmente é um proxy transformador quem o gera, não a sua API.
- 204
No Content
Deu certo e não há corpo na resposta.
Quando usar: Ideal para DELETE e para PUT/PATCH que não devolvem o recurso. Não envie corpo junto.
- 205
Reset Content
Deu certo e o cliente deve limpar a visão do documento, por exemplo um formulário.
Quando usar: Muito pouco usado. Serve para limpar um formulário depois do envio.
- 206
Partial Content
O servidor devolveu só uma parte do recurso, como pedido por um cabeçalho Range.
Quando usar: Downloads retomáveis e streaming de vídeo. Envie Content-Range e Accept-Ranges.
- 207
Multi-Status
O corpo traz vários resultados independentes, um por sub-operação (WebDAV).
Quando usar: Em operações em lote, devolva 207 com o status de cada item em vez de falhar tudo por causa de um erro.
- 208
Already Reported
Os membros do binding já foram listados numa parte anterior da resposta (WebDAV).
Quando usar: Específico de WebDAV. Não é necessário em APIs comuns.
- 226
IM Used
O servidor aplicou uma ou mais manipulações de instância (delta encoding) ao recurso.
Quando usar: Praticamente não aparece hoje.
- 300
Multiple Choices
Há várias representações possíveis e o cliente pode escolher uma.
Quando usar: Raro na prática. Para negociação de conteúdo, prefira os cabeçalhos Accept.
- 301
Moved Permanently
O recurso mudou de endereço para sempre. Use a nova URL do cabeçalho Location.
Quando usar: Para migrar URLs mantendo SEO. Clientes podem trocar POST por GET; se precisa manter o método, use 308.
- 302
Found
Redirecionamento temporário para outra URL.
Quando usar: Redirecionamentos temporários simples (por exemplo, login). Para ser explícito sobre o método, prefira 303 ou 307.
- 303
See Other
A resposta está em outra URL e deve ser buscada com GET.
Quando usar: Depois de um POST, redirecione para a página de resultado (padrão Post/Redirect/Get) evitando reenvio do formulário.
- 304
Not Modified
O recurso não mudou desde a versão que o cliente já tem em cache.
Quando usar: Resposta a requisições condicionais (If-None-Match, If-Modified-Since). Não envie corpo; reenvie ETag e Cache-Control.
- 305
Use Proxy
Antigamente indicava que o recurso só era acessível por um proxy. Está obsoleto.
Quando usar: Não use. Navegadores a ignoram por motivos de segurança.
- 307
Temporary Redirect
Redirecionamento temporário que mantém o método e o corpo da requisição.
Quando usar: Use quando um POST ou PUT precisa ser repetido no novo endereço, por exemplo em failover ou HTTP para HTTPS.
- 308
Permanent Redirect
Redirecionamento permanente que mantém o método e o corpo da requisição.
Quando usar: Versão permanente do 307: use ao mover um endpoint de API de forma definitiva sem trocar POST por GET.
- 400
Bad Request
O servidor não entendeu a requisição por erro de sintaxe, cabeçalhos ou corpo malformado.
Quando usar: JSON inválido, parâmetro com tipo errado, cabeçalho ausente. Se a sintaxe está certa mas as regras de negócio falham, use 422.
- 401
Unauthorized
A requisição não tem credenciais válidas. Apesar do nome, trata de autenticação.
Quando usar: 401 = "quem é você?" (token ausente, inválido ou expirado; envie WWW-Authenticate). 403 = "sei quem é, mas não pode".
- 402
Payment Required
Reservado para uso futuro com pagamentos digitais.
Quando usar: Alguns serviços usam para planos expirados ou cotas pagas esgotadas. Documente se adotar.
- 403
Forbidden
O servidor entendeu a requisição e se recusa a executá-la. Autenticar de novo não resolve.
Quando usar: Usuário autenticado sem permissão para o recurso. Para esconder a existência do recurso, 404 também é aceitável.
- 404
Not Found
O servidor não encontrou o recurso pedido.
Quando usar: ID ou rota inexistente. Não use para lista vazia (devolva 200 com []). Se o recurso existiu e foi removido de vez, considere 410.
- 405
Method Not Allowed
O método HTTP não é aceito para este recurso.
Quando usar: Obrigatório enviar o cabeçalho Allow com os métodos aceitos (ex.: DELETE em endpoint só de leitura).
- 406
Not Acceptable
O servidor não consegue produzir nenhuma representação aceita pelos cabeçalhos Accept do cliente.
Quando usar: Cliente pede application/xml e a API só fala JSON.
- 407
Proxy Authentication Required
Como o 401, mas a autenticação é exigida pelo proxy.
Quando usar: Gerado por proxies; envia Proxy-Authenticate. Raramente vem da aplicação.
- 408
Request Timeout
O servidor esperou demais para receber a requisição completa.
Quando usar: Normalmente gerado pelo servidor ou balanceador. O cliente pode repetir a requisição.
- 409
Conflict
A requisição conflita com o estado atual do recurso.
Quando usar: Valor único duplicado (e-mail já cadastrado), edição concorrente com versão antiga, transição de estado inválida. Explique o conflito no corpo.
- 410
Gone
O recurso foi removido de forma permanente e não deve voltar.
Quando usar: Mais informativo que 404 para endpoints descontinuados ou conteúdo apagado de vez.
- 411
Length Required
O servidor exige o cabeçalho Content-Length.
Quando usar: Upload sem tamanho declarado num endpoint que não aceita chunked.
- 412
Precondition Failed
Uma condição dos cabeçalhos (If-Match, If-Unmodified-Since) não foi satisfeita.
Quando usar: Controle otimista de concorrência: o ETag enviado não bate com o atual.
- 413
Content Too Large
O corpo da requisição é maior do que o servidor aceita.
Quando usar: Limite de upload excedido. Informe o tamanho máximo na mensagem de erro.
- 414
URI Too Long
A URL é mais longa do que o servidor aceita.
Quando usar: Muitos parâmetros na query string. Mova os dados para o corpo de um POST.
- 415
Unsupported Media Type
O formato do corpo (Content-Type) não é suportado.
Quando usar: Cliente envia text/plain ou XML para um endpoint que só aceita application/json.
- 416
Range Not Satisfiable
O intervalo pedido no cabeçalho Range está fora do tamanho do recurso.
Quando usar: Devolva Content-Range: bytes */tamanho para o cliente se corrigir.
- 417
Expectation Failed
O servidor não pode cumprir a expectativa do cabeçalho Expect.
Quando usar: Raro; ocorre com Expect: 100-continue em servidores que não o suportam.
- 418
I'm a teapot
Piada de 1º de abril (HTCPCP): o servidor é um bule de chá e não faz café.
Quando usar: Não use para erros reais. Alguns serviços a usam para barrar bots ou como easter egg.
- 421
Misdirected Request
A requisição foi enviada a um servidor que não consegue produzir uma resposta para ela.
Quando usar: Aparece em HTTP/2 quando uma conexão reaproveitada chega ao host errado. O cliente deve abrir outra conexão.
- 422
Unprocessable Content
A sintaxe está correta, mas o conteúdo não pôde ser processado por falhar regras de validação.
Quando usar: 400 = formato quebrado; 422 = formato válido com dados semanticamente inválidos (e-mail mal formado, data no passado). Liste os erros por campo.
- 423
Locked
O recurso está bloqueado (WebDAV).
Quando usar: Útil para recursos com bloqueio explícito de edição por outro usuário.
- 424
Failed Dependency
A requisição falhou porque dependia de outra que falhou (WebDAV).
Quando usar: Dentro de 207, marca itens que não rodaram por causa de uma falha anterior.
- 425
Too Early
O servidor não quer processar uma requisição que pode ser reproduzida (TLS early data).
Quando usar: Gerado por servidores atrás de TLS 1.3 com 0-RTT; o cliente repete após o handshake.
- 426
Upgrade Required
O cliente precisa trocar de protocolo para continuar.
Quando usar: Envie o cabeçalho Upgrade indicando o protocolo exigido (por exemplo TLS ou WebSocket).
- 428
Precondition Required
O servidor exige que a requisição seja condicional.
Quando usar: Obrigue If-Match em PUT/PATCH para evitar sobrescrever alterações de outros clientes.
- 429
Too Many Requests
O cliente enviou requisições demais num período (rate limiting).
Quando usar: Envie Retry-After (segundos ou data) e, se possível, cabeçalhos com limite e saldo. Clientes devem esperar e usar backoff.
- 431
Request Header Fields Too Large
Os cabeçalhos, em conjunto ou um deles, são grandes demais.
Quando usar: Costuma ser excesso de cookies ou token gigante. Limpe cookies ou reduza o cabeçalho.
- 451
Unavailable For Legal Reasons
O recurso foi bloqueado por exigência legal.
Quando usar: Ordem judicial, censura regional ou restrição de licença. Referência ao livro Fahrenheit 451.
- 499
Client Closed Request
O cliente encerrou a conexão antes de o servidor responder. Usado só em logs do nginx.
Quando usar: Aparece em logs quando clientes desistem por timeout. Muitos 499 indicam respostas lentas.
- 500
Internal Server Error
Erro inesperado no servidor impediu o atendimento da requisição.
Quando usar: Exceção não tratada. Registre em log com um ID de correlação e não exponha stack trace ao cliente.
- 501
Not Implemented
O servidor não suporta a funcionalidade ou o método pedido.
Quando usar: Funcionalidade planejada e ainda não construída, ou método desconhecido. Diferente de 405, que vale para um recurso específico.
- 502
Bad Gateway
Um gateway ou proxy recebeu uma resposta inválida do servidor de origem.
Quando usar: Origem caiu ou respondeu lixo. Verifique se o app está no ar e se o proxy aponta para a porta certa.
- 503
Service Unavailable
O servidor não pode atender no momento, por sobrecarga ou manutenção.
Quando usar: Manutenção planejada ou sobrecarga: envie Retry-After. É a resposta certa para health checks falhando durante o deploy.
- 504
Gateway Timeout
O gateway não recebeu resposta do servidor de origem a tempo.
Quando usar: Origem lenta demais. Aumente o timeout do proxy só se fizer sentido; melhor otimizar ou tornar a operação assíncrona (202).
- 505
HTTP Version Not Supported
O servidor não suporta a versão do HTTP usada na requisição.
Quando usar: Raro; clientes muito antigos ou protocolos mal configurados.
- 506
Variant Also Negotiates
Erro de configuração na negociação transparente de conteúdo.
Quando usar: Praticamente nunca visto.
- 507
Insufficient Storage
O servidor não tem espaço para guardar o necessário para concluir a requisição (WebDAV).
Quando usar: Disco ou cota cheia no servidor.
- 508
Loop Detected
O servidor encontrou um laço infinito ao processar a requisição (WebDAV).
Quando usar: Referências circulares em operações recursivas.
- 510
Not Extended
O servidor exige extensões adicionais da requisição. Obsoleto.
Quando usar: Quase nunca visto; não use.
- 511
Network Authentication Required
O cliente precisa se autenticar para acessar a rede.
Quando usar: Gerado por portais cativos (Wi-Fi de hotel ou aeroporto), não pela sua API. Clientes de API podem ver isso por engano.
- 520
Web Server Returned an Unknown Error
A origem devolveu algo que o Cloudflare não entendeu ou fechou a conexão de forma inesperada.
Quando usar: Veja logs da origem: crash, cabeçalhos enormes ou resposta vazia.
- 521
Web Server Is Down
O Cloudflare não conseguiu conectar ao servidor de origem, que recusou a conexão.
Quando usar: Origem fora do ar ou firewall bloqueando os IPs do Cloudflare.
- 522
Connection Timed Out
O Cloudflare não completou a conexão TCP com a origem a tempo.
Quando usar: Origem sobrecarregada, rota de rede lenta ou IP errado no DNS.
- 523
Origin Is Unreachable
O Cloudflare não conseguiu alcançar a origem, normalmente por problema de DNS ou de rota.
Quando usar: Confira o registro DNS da origem e a conectividade.
- 524
A Timeout Occurred
A conexão com a origem foi feita, mas ela não respondeu dentro do limite (cerca de 100 segundos).
Quando usar: Requisições longas: mova para processamento assíncrono (202) ou envie dados progressivamente.