Web e marketing

Referência de Códigos de Status HTTP

Busque e aprenda o significado, a causa típica e o uso de cada código de status HTTP comum, com snippets cURL/Python/JS/PHP.

100 Continue #

Resposta interina que sinaliza que o servidor recebeu os cabeçalhos e o cliente pode enviar o corpo. RFC 9110 §15.2.1.

Causa comum

O cliente enviou Expect: 100-continue para testar se o servidor aceitará um corpo grande antes de transmiti-lo.

Quando usar

Usado entre cabeçalhos e corpo de uploads longos (PUT, POST) para o cliente não gastar banda à toa.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 100 Continue

import requests
r = requests.get("https://example.com/path")
if r.status_code == 100:
    print("Continue")

const r = await fetch("https://example.com/path");
if (r.status === 100) {
  console.log("Continue");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 100);
// or:
http_response_code(100);

101 Switching Protocols #

O servidor concorda em trocar para outro protocolo de aplicação na mesma conexão TCP, listado em Upgrade. RFC 9110 §15.2.2.

Causa comum

O cliente pediu Upgrade (em geral WebSocket ou HTTP/2 sobre h2c) e o servidor aceitou.

Quando usar

Handshakes de WebSocket são o caso dominante hoje. Após 101 a conexão deixa de ser HTTP.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 101 Switching Protocols

import requests
r = requests.get("https://example.com/path")
if r.status_code == 101:
    print("Switching Protocols")

const r = await fetch("https://example.com/path");
if (r.status === 101) {
  console.log("Switching Protocols");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 101);
// or:
http_response_code(101);

200 OK #

Resposta padrão de sucesso — a requisição foi atendida e o corpo traz a representação pedida. RFC 9110 §15.3.1.

Causa comum

Requisição válida, autorizada e atendida sem redirecionamento.

Quando usar

GETs que retornam dados, POSTs/PUTs processados de imediato, respostas sadias de API.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 200 OK

import requests
r = requests.get("https://example.com/path")
if r.status_code == 200:
    print("OK")

const r = await fetch("https://example.com/path");
if (r.status === 200) {
  console.log("OK");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 200);
// or:
http_response_code(200);

201 Created #

A requisição teve sucesso e um novo recurso foi criado em consequência. O cabeçalho Location DEVE apontar para o novo recurso. RFC 9110 §15.3.2.

Causa comum

Um POST ou PUT criou um recurso (linha de banco, arquivo, usuário, etc.).

Quando usar

Use após criar recursos REST. Devolva a representação no corpo e Location no header.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 201 Created

import requests
r = requests.get("https://example.com/path")
if r.status_code == 201:
    print("Created")

const r = await fetch("https://example.com/path");
if (r.status === 201) {
  console.log("Created");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 201);
// or:
http_response_code(201);

202 Accepted #

A requisição foi aceita para processamento, mas ainda não terminou. O processamento pode falhar mais tarde. RFC 9110 §15.3.3.

Causa comum

Processamento assíncrono enfileirado. O trabalho ocorre depois.

Quando usar

Jobs em background, importação em lote, qualquer coisa que retorne uma URL de status enquanto roda.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 202 Accepted

import requests
r = requests.get("https://example.com/path")
if r.status_code == 202:
    print("Accepted")

const r = await fetch("https://example.com/path");
if (r.status === 202) {
  console.log("Accepted");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 202);
// or:
http_response_code(202);

204 No Content #

A requisição teve sucesso; a resposta deliberadamente não traz corpo. Cabeçalhos podem carregar metadados. RFC 9110 §15.3.5.

Causa comum

Update ou delete que não precisa devolver representação.

Quando usar

Respostas de DELETE, PUT/PATCH onde o cliente já tem a nova representação, endpoints de salvar-e-ficar.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 204 No Content

import requests
r = requests.get("https://example.com/path")
if r.status_code == 204:
    print("No Content")

const r = await fetch("https://example.com/path");
if (r.status === 204) {
  console.log("No Content");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 204);
// or:
http_response_code(204);

206 Partial Content #

O servidor devolveu apenas parte da representação em resposta a uma requisição com Range. RFC 9110 §15.3.7.

Causa comum

O cliente pediu um intervalo de bytes via cabeçalho Range.

Quando usar

Downloads retomáveis, streaming de vídeo com seek e download em chunks paralelos.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 206 Partial Content

import requests
r = requests.get("https://example.com/path")
if r.status_code == 206:
    print("Partial Content")

const r = await fetch("https://example.com/path");
if (r.status === 206) {
  console.log("Partial Content");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 206);
// or:
http_response_code(206);

301 Moved Permanently #

O recurso de destino tem um novo URI permanente. Clientes DEVERIAM atualizar favoritos e buscadores reindexar. RFC 9110 §15.4.2.

Causa comum

Mudança de URL canônica — renomeação de domínio, ajuste de slug, migração para HTTPS.

Quando usar

Redirecionamentos de longo prazo. Evite 301 em redirecionamentos curtos por causa do cache agressivo.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 301 Moved Permanently

import requests
r = requests.get("https://example.com/path")
if r.status_code == 301:
    print("Moved Permanently")

const r = await fetch("https://example.com/path");
if (r.status === 301) {
  console.log("Moved Permanently");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 301);
// or:
http_response_code(301);

302 Found #

O recurso reside temporariamente em outra URI. Clientes deveriam buscar a nova URI sem mudar a semântica do método, mas historicamente reescrevem POST para GET. RFC 9110 §15.4.3.

Causa comum

Redirecionamento temporário com comportamento histórico de troca de método, mantido por compatibilidade.

Quando usar

Código legado. Em APIs novas prefira 303 ou 307 para evitar ambiguidade.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 302 Found

import requests
r = requests.get("https://example.com/path")
if r.status_code == 302:
    print("Found")

const r = await fetch("https://example.com/path");
if (r.status === 302) {
  console.log("Found");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 302);
// or:
http_response_code(302);

303 See Other #

Redireciona para um recurso que deve ser buscado com GET, independente do método original. RFC 9110 §15.4.4.

Causa comum

Após um POST não idempotente, o servidor manda o cliente para uma página de confirmação ou recurso recém-criado.

Quando usar

Padrão Post/Redirect/Get. Sempre reescreve para GET, ideal após envio de formulário.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 303 See Other

import requests
r = requests.get("https://example.com/path")
if r.status_code == 303:
    print("See Other")

const r = await fetch("https://example.com/path");
if (r.status === 303) {
  console.log("See Other");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 303);
// or:
http_response_code(303);

304 Not Modified #

A representação em cache do cliente continua válida; nenhum corpo é enviado. RFC 9110 §15.4.5.

Causa comum

O cliente enviou If-None-Match ou If-Modified-Since e os validadores bateram com o recurso atual.

Quando usar

Respostas condicionais a GETs para cache. Economiza banda em estáticos e respostas de API inalteradas.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 304 Not Modified

import requests
r = requests.get("https://example.com/path")
if r.status_code == 304:
    print("Not Modified")

const r = await fetch("https://example.com/path");
if (r.status === 304) {
  console.log("Not Modified");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 304);
// or:
http_response_code(304);

307 Temporary Redirect #

Como o 302, mas preserva explicitamente método e corpo da requisição. RFC 9110 §15.4.8.

Causa comum

Redirecionamento de curto prazo em que o POST/PUT original deve ser refeito na nova URI.

Quando usar

Redirecionamentos de manutenção, roteamento A/B ou geo, mantendo o método.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 307 Temporary Redirect

import requests
r = requests.get("https://example.com/path")
if r.status_code == 307:
    print("Temporary Redirect")

const r = await fetch("https://example.com/path");
if (r.status === 307) {
  console.log("Temporary Redirect");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 307);
// or:
http_response_code(307);

308 Permanent Redirect #

Como o 301, mas preserva explicitamente método e corpo. RFC 9110 §15.4.9.

Causa comum

Mudança canônica de URI para métodos não-GET (upgrade para HTTPS de APIs POST, renomeação de rota).

Quando usar

Redirecionamentos permanentes em APIs REST. Use no lugar de 301 quando o método não pode ser reescrito.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 308 Permanent Redirect

import requests
r = requests.get("https://example.com/path")
if r.status_code == 308:
    print("Permanent Redirect")

const r = await fetch("https://example.com/path");
if (r.status === 308) {
  console.log("Permanent Redirect");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 308);
// or:
http_response_code(308);

400 Bad Request #

O servidor não consegue processar a requisição por erro do cliente: sintaxe inválida, framing ruim, roteamento enganoso. RFC 9110 §15.5.1.

Causa comum

JSON quebrado, campo obrigatório ausente, header malformado, cookie grande demais.

Quando usar

Erro genérico do cliente. Prefira códigos mais específicos (422, 411, 415) quando aplicáveis.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 400 Bad Request

import requests
r = requests.get("https://example.com/path")
if r.status_code == 400:
    print("Bad Request")

const r = await fetch("https://example.com/path");
if (r.status === 400) {
  console.log("Bad Request");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 400);
// or:
http_response_code(400);

401 Unauthorized #

A requisição não traz credenciais válidas. A resposta DEVE incluir um WWW-Authenticate listando esquemas aceitos. RFC 9110 §15.5.2.

Causa comum

Token ausente, expirado ou inválido; sem cabeçalho Authorization onde é exigido.

Quando usar

Endpoints atrás de autenticação. Distinto de 403 — 401 é "não autenticado", 403 é "autenticado mas sem permissão".

curl -i -X HEAD https://example.com/path
# HTTP/1.1 401 Unauthorized

import requests
r = requests.get("https://example.com/path")
if r.status_code == 401:
    print("Unauthorized")

const r = await fetch("https://example.com/path");
if (r.status === 401) {
  console.log("Unauthorized");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 401);
// or:
http_response_code(401);

403 Forbidden #

O servidor entendeu a requisição mas se recusa a autorizar. RFC 9110 §15.5.4.

Causa comum

Usuário autenticado sem permissão ou recurso bloqueado por IP/região.

Quando usar

Falhas de autorização, listas de IP, controle baseado em papéis.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 403 Forbidden

import requests
r = requests.get("https://example.com/path")
if r.status_code == 403:
    print("Forbidden")

const r = await fetch("https://example.com/path");
if (r.status === 403) {
  console.log("Forbidden");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 403);
// or:
http_response_code(403);

404 Not Found #

O servidor não encontrou representação atual do recurso. Pode ser usado para esconder um 403. RFC 9110 §15.5.5.

Causa comum

Erro de digitação na URL, recurso apagado ou que nunca existiu.

Quando usar

Resposta padrão para rotas e recursos ausentes. Cacheia menos agressivamente que 410.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 404 Not Found

import requests
r = requests.get("https://example.com/path")
if r.status_code == 404:
    print("Not Found")

const r = await fetch("https://example.com/path");
if (r.status === 404) {
  console.log("Not Found");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 404);
// or:
http_response_code(404);

405 Method Not Allowed #

O método não é suportado no recurso. A resposta DEVE incluir um cabeçalho Allow com os métodos suportados. RFC 9110 §15.5.6.

Causa comum

DELETE numa coleção apenas leitura, POST em recurso singleton, etc.

Quando usar

APIs REST que querem ser explícitas sobre verbos permitidos.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 405 Method Not Allowed

import requests
r = requests.get("https://example.com/path")
if r.status_code == 405:
    print("Method Not Allowed")

const r = await fetch("https://example.com/path");
if (r.status === 405) {
  console.log("Method Not Allowed");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 405);
// or:
http_response_code(405);

406 Not Acceptable #

O servidor não consegue produzir representação compatível com os cabeçalhos Accept-*. RFC 9110 §15.5.7.

Causa comum

Cliente pediu application/xml mas só há application/json.

Quando usar

Negociação estrita de conteúdo. Muitas APIs apenas devolvem JSON em vez de retornar 406.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 406 Not Acceptable

import requests
r = requests.get("https://example.com/path")
if r.status_code == 406:
    print("Not Acceptable")

const r = await fetch("https://example.com/path");
if (r.status === 406) {
  console.log("Not Acceptable");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 406);
// or:
http_response_code(406);

408 Request Timeout #

O servidor desistiu de esperar o cliente terminar a requisição. RFC 9110 §15.5.9.

Causa comum

Conexão lenta, upload pela metade, keep-alive ocioso além do timeout.

Quando usar

Proxies reversos e load balancers à frente de clientes lentos.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 408 Request Timeout

import requests
r = requests.get("https://example.com/path")
if r.status_code == 408:
    print("Request Timeout")

const r = await fetch("https://example.com/path");
if (r.status === 408) {
  console.log("Request Timeout");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 408);
// or:
http_response_code(408);

409 Conflict #

A requisição conflita com o estado atual do recurso. RFC 9110 §15.5.10.

Causa comum

Dois clientes editando o mesmo registro simultaneamente; violação de constraint única; PUT com ETag desatualizada.

Quando usar

Controle de concorrência otimista, criação idempotente.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 409 Conflict

import requests
r = requests.get("https://example.com/path")
if r.status_code == 409:
    print("Conflict")

const r = await fetch("https://example.com/path");
if (r.status === 409) {
  console.log("Conflict");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 409);
// or:
http_response_code(409);

410 Gone #

O recurso foi removido propositalmente e não voltará. RFC 9110 §15.5.11.

Causa comum

Conteúdo deletado de forma permanente; endpoint de API descontinuado.

Quando usar

Páginas removidas em que você quer que crawlers tirem a URL mais rápido que com 404.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 410 Gone

import requests
r = requests.get("https://example.com/path")
if r.status_code == 410:
    print("Gone")

const r = await fetch("https://example.com/path");
if (r.status === 410) {
  console.log("Gone");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 410);
// or:
http_response_code(410);

411 Length Required #

A requisição falta o cabeçalho Content-Length onde o servidor exige. RFC 9110 §15.5.12.

Causa comum

Cliente em streaming que não bufferizou o corpo nem usou chunked transfer encoding.

Quando usar

Servidores que proíbem upload chunked em certos endpoints.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 411 Length Required

import requests
r = requests.get("https://example.com/path")
if r.status_code == 411:
    print("Length Required")

const r = await fetch("https://example.com/path");
if (r.status === 411) {
  console.log("Length Required");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 411);
// or:
http_response_code(411);

413 Content Too Large #

O corpo é maior do que o servidor está disposto a aceitar. RFC 9110 §15.5.14. Renomeado de "Payload Too Large" na RFC 9110.

Causa comum

Upload acima do limite configurado; arquivo maior que o tamanho máximo do formulário.

Quando usar

Endpoints de upload, APIs JSON com limite de corpo.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 413 Content Too Large

import requests
r = requests.get("https://example.com/path")
if r.status_code == 413:
    print("Content Too Large")

const r = await fetch("https://example.com/path");
if (r.status === 413) {
  console.log("Content Too Large");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 413);
// or:
http_response_code(413);

414 URI Too Long #

A URI da requisição é maior do que o servidor está disposto a interpretar. RFC 9110 §15.5.15.

Causa comum

Query strings enormes (em geral de formulários enviados com method=GET) ou tokens embutidos na URL.

Quando usar

Quando usuários atingem o endpoint com URLs anormalmente longas — troque o formulário para POST.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 414 URI Too Long

import requests
r = requests.get("https://example.com/path")
if r.status_code == 414:
    print("URI Too Long")

const r = await fetch("https://example.com/path");
if (r.status === 414) {
  console.log("URI Too Long");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 414);
// or:
http_response_code(414);

415 Unsupported Media Type #

O servidor recusa aceitar o corpo no formato descrito por Content-Type. RFC 9110 §15.5.16.

Causa comum

Mandar application/xml para um endpoint só JSON, ou Content-Type errado/ausente.

Quando usar

APIs REST que aceitam estritamente um ou dois media types.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 415 Unsupported Media Type

import requests
r = requests.get("https://example.com/path")
if r.status_code == 415:
    print("Unsupported Media Type")

const r = await fetch("https://example.com/path");
if (r.status === 415) {
  console.log("Unsupported Media Type");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 415);
// or:
http_response_code(415);

418 I’m a teapot #

Piada de 1º de abril da RFC 2324 (HTCPCP). Alguns servidores devolvem como erro genérico de "recuso a operar". Não é status real de produção.

Causa comum

Software que devolve 418 de propósito, em geral em armadilhas para abuso ou easter eggs.

Quando usar

Apenas easter eggs. Não use em APIs reais — muitos proxies e clientes não reconhecem.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 418 I’m a teapot

import requests
r = requests.get("https://example.com/path")
if r.status_code == 418:
    print("I’m a teapot")

const r = await fetch("https://example.com/path");
if (r.status === 418) {
  console.log("I’m a teapot");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 418);
// or:
http_response_code(418);

422 Unprocessable Content #

A sintaxe está ok, mas o servidor não consegue processar o conteúdo semântico. RFC 9110 §15.5.21. Originalmente em WebDAV (RFC 4918).

Causa comum

Erros de validação em payload JSON estruturalmente válido — campo obrigatório vazio, valor fora do range.

Quando usar

Validação de formulário em APIs modernas. Mais limpo que 400 porque a requisição é sintaticamente válida.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 422 Unprocessable Content

import requests
r = requests.get("https://example.com/path")
if r.status_code == 422:
    print("Unprocessable Content")

const r = await fetch("https://example.com/path");
if (r.status === 422) {
  console.log("Unprocessable Content");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 422);
// or:
http_response_code(422);

423 Locked #

O recurso está bloqueado. RFC 4918 (WebDAV).

Causa comum

Recurso WebDAV em que outro usuário detém um lock exclusivo.

Quando usar

Servidores de colaboração de documentos, frontends de controle de versão.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 423 Locked

import requests
r = requests.get("https://example.com/path")
if r.status_code == 423:
    print("Locked")

const r = await fetch("https://example.com/path");
if (r.status === 423) {
  console.log("Locked");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 423);
// or:
http_response_code(423);

425 Too Early #

O servidor não quer processar uma requisição que pode ser repetida, em geral por ter sido enviada em TLS 1.3 0-RTT (early data). RFC 8470.

Causa comum

Requisição em TLS 1.3 0-RTT que o servidor considera insegura para replay.

Quando usar

Proteja endpoints não idempotentes contra replay durante handshakes 0-RTT.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 425 Too Early

import requests
r = requests.get("https://example.com/path")
if r.status_code == 425:
    print("Too Early")

const r = await fetch("https://example.com/path");
if (r.status === 425) {
  console.log("Too Early");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 425);
// or:
http_response_code(425);

428 Precondition Required #

O servidor de origem exige que a requisição seja condicional. RFC 6585.

Causa comum

O servidor quer que clientes usem If-Match / If-Unmodified-Since para evitar conflitos de atualização perdida.

Quando usar

APIs com locking otimista que recusam escrita incondicional.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 428 Precondition Required

import requests
r = requests.get("https://example.com/path")
if r.status_code == 428:
    print("Precondition Required")

const r = await fetch("https://example.com/path");
if (r.status === 428) {
  console.log("Precondition Required");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 428);
// or:
http_response_code(428);

429 Too Many Requests #

O usuário enviou muitas requisições em determinado intervalo. RFC 6585.

Causa comum

Limite de taxa atingido; a resposta normalmente inclui Retry-After.

Quando usar

APIs com rate limit, throttling de login, mitigação de abuso.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 429 Too Many Requests

import requests
r = requests.get("https://example.com/path")
if r.status_code == 429:
    print("Too Many Requests")

const r = await fetch("https://example.com/path");
if (r.status === 429) {
  console.log("Too Many Requests");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 429);
// or:
http_response_code(429);

431 Request Header Fields Too Large #

O servidor recusa processar a requisição porque os cabeçalhos são grandes demais. RFC 6585.

Causa comum

Cookie excessivo, Referer ou Authorization muito longos.

Quando usar

Quando cookies de sessão crescem além do buffer do proxy reverso; reduza ou mova estado para o corpo.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 431 Request Header Fields Too Large

import requests
r = requests.get("https://example.com/path")
if r.status_code == 431:
    print("Request Header Fields Too Large")

const r = await fetch("https://example.com/path");
if (r.status === 431) {
  console.log("Request Header Fields Too Large");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 431);
// or:
http_response_code(431);

451 Unavailable For Legal Reasons #

O recurso está indisponível por exigência legal — ordem de remoção, bloqueio geográfico ou DMCA. RFC 7725.

Causa comum

Ordem judicial, takedown regulatório, resposta a direito de apagamento sob LGPD/GDPR.

Quando usar

Times de compliance que precisam ser transparentes sobre o motivo do bloqueio.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 451 Unavailable For Legal Reasons

import requests
r = requests.get("https://example.com/path")
if r.status_code == 451:
    print("Unavailable For Legal Reasons")

const r = await fetch("https://example.com/path");
if (r.status === 451) {
  console.log("Unavailable For Legal Reasons");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 451);
// or:
http_response_code(451);

500 Internal Server Error #

O servidor encontrou condição inesperada que impediu atender à requisição. RFC 9110 §15.6.1.

Causa comum

Exceção não tratada, bug, dependência quebrada, query descontrolada.

Quando usar

Catch-all de erro de servidor. Sempre logue stack trace e request ID para os usuários poderem citar.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 500 Internal Server Error

import requests
r = requests.get("https://example.com/path")
if r.status_code == 500:
    print("Internal Server Error")

const r = await fetch("https://example.com/path");
if (r.status === 500) {
  console.log("Internal Server Error");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 500);
// or:
http_response_code(500);

501 Not Implemented #

O servidor não suporta a funcionalidade necessária para atender à requisição. RFC 9110 §15.6.2.

Causa comum

Método desconhecido, feature flag desligada, caminho stub.

Quando usar

Endpoints existentes mas ainda não implementados. Prefira 405 quando outros métodos funcionam.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 501 Not Implemented

import requests
r = requests.get("https://example.com/path")
if r.status_code == 501:
    print("Not Implemented")

const r = await fetch("https://example.com/path");
if (r.status === 501) {
  console.log("Not Implemented");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 501);
// or:
http_response_code(501);

502 Bad Gateway #

O gateway ou proxy obteve resposta inválida do servidor upstream. RFC 9110 §15.6.3.

Causa comum

Upstream devolveu HTTP malformado, conexão caiu no meio da resposta ou a aplicação travou.

Quando usar

Proxies reversos (Nginx, Cloudflare, ALB) quando a aplicação atrás falha.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 502 Bad Gateway

import requests
r = requests.get("https://example.com/path")
if r.status_code == 502:
    print("Bad Gateway")

const r = await fetch("https://example.com/path");
if (r.status === 502) {
  console.log("Bad Gateway");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 502);
// or:
http_response_code(502);

503 Service Unavailable #

O servidor não consegue tratar a requisição agora, em geral por manutenção ou sobrecarga. RFC 9110 §15.6.4.

Causa comum

Janela de manutenção, fila cheia, autoscaler atrasado, brown-out deliberado.

Quando usar

Indisponibilidade planejada ou proteção contra sobrecarga. Sempre defina Retry-After para o cliente recuar.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 503 Service Unavailable

import requests
r = requests.get("https://example.com/path")
if r.status_code == 503:
    print("Service Unavailable")

const r = await fetch("https://example.com/path");
if (r.status === 503) {
  console.log("Service Unavailable");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 503);
// or:
http_response_code(503);

504 Gateway Timeout #

O gateway ou proxy não recebeu resposta a tempo do servidor upstream. RFC 9110 §15.6.5.

Causa comum

Upstream demorou mais do que o timeout configurado no proxy.

Quando usar

Código lento da aplicação, query travada no banco, API de terceiro travada.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 504 Gateway Timeout

import requests
r = requests.get("https://example.com/path")
if r.status_code == 504:
    print("Gateway Timeout")

const r = await fetch("https://example.com/path");
if (r.status === 504) {
  console.log("Gateway Timeout");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 504);
// or:
http_response_code(504);

505 HTTP Version Not Supported #

O servidor não suporta a versão maior de HTTP da requisição. RFC 9110 §15.6.6.

Causa comum

Cliente fala HTTP/2 com servidor que só faz HTTP/1.0, ou envia versão desconhecida.

Quando usar

Raro na prática. Bordas mal configuradas ou clientes muito antigos.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 505 HTTP Version Not Supported

import requests
r = requests.get("https://example.com/path")
if r.status_code == 505:
    print("HTTP Version Not Supported")

const r = await fetch("https://example.com/path");
if (r.status === 505) {
  console.log("HTTP Version Not Supported");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 505);
// or:
http_response_code(505);

511 Network Authentication Required #

O cliente precisa se autenticar para usar a rede — em geral um portal cativo. RFC 6585.

Causa comum

Wi-Fi de hotel ou aeroporto interceptando o tráfego até login.

Quando usar

Portais cativos em redes de passagem. Servidores não devolvem isso por conta própria.

curl -i -X HEAD https://example.com/path
# HTTP/1.1 511 Network Authentication Required

import requests
r = requests.get("https://example.com/path")
if r.status_code == 511:
    print("Network Authentication Required")

const r = await fetch("https://example.com/path");
if (r.status === 511) {
  console.log("Network Authentication Required");
}

// Laravel / generic PHP
return response()->json(['ok' => false], 511);
// or:
http_response_code(511);

O que são códigos de status HTTP?

Um código de status HTTP é o número de três dígitos que o servidor devolve no início de cada resposta. Agrupam-se em cinco famílias: 1xx informacional, 2xx sucesso, 3xx redirecionamento, 4xx erro do cliente e 5xx erro do servidor. Os códigos estão definidos na RFC 9110 (a especificação consolidada de 2022 que substitui a série 7230–7235), com extensões na RFC 6585 (4xx/5xx adicionais), RFC 7725 (451), RFC 4918 (WebDAV) e RFC 8470 (425). Ler o status corretamente é a diferença entre corrigir um bug em cinco minutos e caçar fantasma a tarde toda: um 404 do CDN significa que o caminho está errado, um 502 do proxy significa que a aplicação caiu e um 401 sem WWW-Authenticate é backend mal configurado. Esta página é um cheat sheet pesquisável — cada cartão traz nome oficial, descrição baseada na RFC, causa típica e trechos prontos para colar em curl, Python, JavaScript ou PHP.

Como usar a referência

Digite um código ou parte de um nome na busca, ou filtre por família com os chips. Cada cartão abre para mostrar a descrição técnica, causas comuns e um snippet em abas que você pode adaptar. Cada código tem âncora própria (ex: #404) para você apontar a doc do time direto para o status.

Famílias de status em resumo

Faixa	Família	Significado
1xx	Informacional	Respostas provisórias; raramente vistas na camada de aplicação.
2xx	Sucesso	A requisição foi recebida, entendida e aceita.
3xx	Redirecionamento	É preciso uma ação adicional (URL diferente, validação de cache, etc.).
4xx	Erro do cliente	A requisição teve algum problema (entrada ruim, falta de auth, método errado).
5xx	Erro do servidor	O servidor falhou em atender a uma requisição aparentemente válida.

Perguntas frequentes

De onde vêm esses códigos?

A RFC 9110 é a especificação canônica de 2022 que consolida a antiga série RFC 7231. Códigos adicionais estão na RFC 6585 (428, 429, 431, 511), RFC 7725 (451), RFC 4918 (WebDAV) e RFC 8470 (425).

Devo usar 401 ou 403?

401 significa "você não está autenticado". 403 significa "você está autenticado mas não tem permissão". O 401 deve incluir um cabeçalho WWW-Authenticate listando esquemas aceitos; o 403 não deveria, porque as credenciais não são o problema.

Qual a diferença entre 301 e 308?

Ambos sinalizam redirecionamento permanente. O 301 historicamente reescreve POST para GET em muitos clientes; o 308 preserva o método e o corpo. Use 308 em APIs novas.

Quando o CDN devolve 502 vs 504?

502 (Bad Gateway) significa que o upstream devolveu dado malformado ou fechou a conexão. 504 (Gateway Timeout) significa que o upstream demorou demais. CloudFront, Cloudflare e Nginx marcam de modo distinto nos logs — ambos indicam problema de aplicação.

Devo retornar 404 ou 410 para conteúdo apagado?

Use 410 quando o recurso foi removido de propósito e definitivamente e você quer que os crawlers removam rápido. 404 serve para erros de digitação e conteúdo que pode voltar; também é uma resposta defensável quando você não quer confirmar a existência do recurso.

Os snippets são seguros para copiar?

São modelos mínimos para leitura e adaptação. Valide entradas, trate erros e respeite a semântica do HTTP no seu código — os exemplos pulam isso por brevidade.