Como diagnosticar erros HTTP 401, 403, 404, 409, 422 e 500 sem chutar

Uma API respondeu 401, você trocou o token e recebeu 403. Depois alterou a URL, chegou a um 404 e começou a mexer em tudo ao mesmo tempo. Esse é o caminho mais curto para transformar um erro simples em três problemas novos. Códigos HTTP não são mensagens decorativas: eles informam em qual camada a requisição parou e reduzem muito o espaço de investigação quando são lidos junto com método, URL, cabeçalhos, corpo e resposta.

Este guia mostra como diagnosticar erros HTTP de forma reproduzível. A ideia não é decorar todos os códigos, e sim construir uma evidência mínima, testar uma hipótese por vez e descobrir se a falha está no cliente, na autenticação, na autorização, na rota, na regra de negócio ou no servidor. Os exemplos usam curl porque ele funciona fora do navegador e facilita repetir exatamente a mesma requisição. Para inspeção rápida, também vale usar o Analisador de URL do IATechNerds, o conversor de curl para código e o formatador de JSON.

Legenda: comece pela requisição que realmente saiu do cliente e avance uma camada por vez.

Antes do código HTTP: confirme que existe uma resposta HTTP

Nem todo erro exibido por um aplicativo é uma resposta HTTP. Mensagens como “Failed to fetch”, “Network Error”, ECONNREFUSED, falha de DNS ou certificado inválido podem acontecer antes de o servidor produzir qualquer status. Se não houve resposta, discutir se o problema é 401 ou 500 não faz sentido.

Abra a aba Network das ferramentas de desenvolvimento do navegador, repita a ação e selecione a requisição. Procure por quatro evidências: URL final, método, status e duração. Se a requisição nem aparece, o problema pode estar no JavaScript antes do fetch. Se aparece como bloqueada, observe a mensagem do navegador: CORS, conteúdo misto, certificado e extensão de privacidade são causas diferentes. Se existe um status numérico, houve resposta HTTP e o roteiro deste artigo se aplica.

No terminal, execute primeiro uma chamada simples e verbosa:

curl -i -v https://api.exemplo.test/v1/clientes

-i inclui os cabeçalhos da resposta. -v mostra detalhes da conexão e da requisição, mas pode revelar tokens e cookies no terminal. Antes de compartilhar o resultado, substitua credenciais por [REMOVIDO]. Não publique um log bruto em fórum, issue ou chat.

Registre também o horário e um identificador de correlação, caso a API envie cabeçalhos como x-request-id, traceparent ou x-correlation-id. Esse valor permite localizar o mesmo evento nos logs do servidor sem depender de adivinhação.

Monte uma requisição mínima que qualquer pessoa consiga repetir

O melhor caso de teste não é um print da mensagem. É uma requisição mínima, sanitizada e completa. Ela deve preservar método, URL, cabeçalhos relevantes e corpo, removendo apenas dados secretos ou pessoais.

Considere esta criação de cliente:

curl --request POST 'https://api.exemplo.test/v1/clientes' \
  --header 'Authorization: Bearer TOKEN_REMOVIDO' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "nome": "Ana",
    "email": "ana@example.test"
  }'

Salve a resposta com cabeçalhos e corpo em arquivos separados:

curl --silent --show-error \
  --dump-header resposta-cabecalhos.txt \
  --output resposta-corpo.json \
  --write-out '%{http_code}\n' \
  --request POST 'https://api.exemplo.test/v1/clientes' \
  --header 'Authorization: Bearer TOKEN_REMOVIDO' \
  --header 'Content-Type: application/json' \
  --data '{"nome":"Ana","email":"ana@example.test"}'

Esse formato evita um erro comum: olhar apenas o número e ignorar o corpo, onde APIs costumam informar campo inválido, permissão ausente ou conflito. Se o corpo for JSON, valide sua sintaxe antes de interpretar. Um proxy pode devolver HTML com status 502, enquanto seu código tenta executar response.json() e produz uma segunda exceção que esconde a primeira.

401: a identidade não foi aceita

O 401 Unauthorized está ligado à autenticação. Apesar do nome histórico, a pergunta prática é: “a API conseguiu reconhecer uma identidade válida para esta requisição?”. Em respostas compatíveis, o servidor pode enviar WWW-Authenticate, indicando o esquema esperado.

Verifique, nesta ordem:

1. O cabeçalho Authorization realmente saiu do cliente? No navegador, confirme em Request Headers.
2. O esquema está correto? Bearer, Basic e chaves proprietárias não são intercambiáveis.
3. O token está completo, sem aspas indevidas, espaço extra ou quebra de linha?
4. Ele expirou? Examine exp somente se for um JWT e sem tratar o conteúdo decodificado como prova de validade. Assinatura e regras do servidor continuam sendo decisivas.
5. O token foi emitido para o ambiente correto? Credencial de homologação geralmente não funciona em produção.
6. Relógios desalinhados estão fazendo um token recém-emitido parecer futuro ou expirado?

Compare uma chamada pública e uma autenticada para a mesma origem. Depois gere uma credencial nova pelo fluxo oficial, sem copiar tokens de logs antigos. Se a nova credencial falha exatamente igual, pare de renovar tokens: investigue público, emissor, escopo e configuração da API.

Não tente “resolver” um 401 colocando token em query string. URLs aparecem em históricos, logs e ferramentas de monitoramento. Credenciais devem seguir o mecanismo documentado pelo serviço.

403: a identidade existe, mas a ação continua proibida

O 403 Forbidden significa que o servidor entendeu a requisição, mas recusou a ação. A diferença operacional para 401 é importante: repetir a mesma autenticação tende a produzir o mesmo resultado. A identidade pode estar válida, porém sem função, escopo, propriedade ou política necessária.

Faça uma matriz pequena com usuário, recurso e ação. Exemplo: a conta A lê o cliente 10, mas não edita; a conta B edita o cliente 10; nenhuma acessa o cliente 20. Esse padrão aponta para autorização por função ou propriedade, não para token quebrado.

Cheque os escopos efetivos retornados pelo provedor, a função do usuário, o tenant/organização, o projeto selecionado e a propriedade do recurso. Em sistemas com múltiplos ambientes, confirme se o identificador pertence ao mesmo tenant da credencial. Um ID válido em outra organização pode resultar em 403 ou até 404, pois alguns serviços ocultam a existência de recursos não autorizados.

Também separe a resposta da aplicação de bloqueios na borda. WAF, CDN ou gateway podem negar IP, país, método, tamanho ou padrão do corpo. Compare cabeçalhos e aparência da resposta. Se o JSON habitual da API virou uma página HTML genérica, talvez a requisição nem tenha alcançado a aplicação.

404 e 405: rota, recurso e método não são a mesma coisa

404 Not Found pode indicar rota inexistente, recurso inexistente ou ocultação deliberada por autorização. Já 405 Method Not Allowed informa que o servidor conhece o alvo, mas não aceita aquele método. Uma API pode permitir GET /clientes/10 e rejeitar POST /clientes/10.

Compare a URL caractere por caractere:

/v1/clientes/10
/v1/cliente/10
/api/v1/clientes/10
/v1/clientes/10/

Não presuma que barra final, maiúsculas ou prefixos são normalizados. Verifique ainda se o cliente seguiu um redirecionamento. Um POST redirecionado de forma inadequada pode chegar ao destino como GET, dependendo do status e do cliente. Use:

curl -I https://api.exemplo.test/clientes/10
curl -i -X OPTIONS https://api.exemplo.test/v1/clientes/10

O primeiro inspeciona cabeçalhos, embora HEAD não seja suportado por toda API. O segundo pode revelar métodos permitidos via cabeçalho Allow, mas também depende da configuração do servidor. A fonte principal continua sendo a documentação da API e sua especificação OpenAPI.

Se a rota existe, teste com um identificador conhecido. Se GET /clientes/10 funciona e GET /clientes/999999 retorna 404, o roteamento está saudável e o problema é o recurso. Se todos retornam 404, revise base URL, versão, deploy e proxy reverso.

409: a requisição é válida, mas conflita com o estado atual

409 Conflict costuma aparecer quando o formato da requisição está correto, porém aplicá-la violaria o estado do recurso. Exemplos: criar um usuário com e-mail já cadastrado, atualizar uma versão antiga, reservar um nome ocupado ou repetir uma operação que não é idempotente.

Leia o corpo procurando campos como code, conflict, currentVersion ou existingId. Para concorrência, APIs podem trabalhar com ETag e If-Match:

curl -i 'https://api.exemplo.test/v1/documentos/42'

curl -i -X PUT 'https://api.exemplo.test/v1/documentos/42' \
  -H 'If-Match: "versao-7"' \
  -H 'Content-Type: application/json' \
  --data '{"titulo":"Versão revisada"}'

Se outro cliente já salvou a versão 8, a atualização baseada na versão 7 deve ser recusada em vez de sobrescrever silenciosamente o trabalho mais novo. A solução não é remover a proteção: recarregue o estado atual, reconcilie a alteração e tente novamente com a versão correta.

Para criação duplicada, decida se a operação deveria ser idempotente. Algumas APIs aceitam uma chave de idempotência para que uma repetição causada por timeout não crie dois registros. Use esse recurso somente conforme a documentação; inventar um cabeçalho não muda o comportamento do servidor.

422: JSON válido não significa dados aceitáveis

O 422 Unprocessable Content normalmente indica que o servidor entendeu o tipo e a sintaxe, mas encontrou problemas semânticos ou de validação. O JSON fecha corretamente, porém um campo obrigatório falta, uma data tem formato inadequado ou uma combinação de valores viola uma regra.

Faça três testes graduais:

{}

{"nome":"Ana"}

{"nome":"Ana","email":"ana@example.test"}

Compare as respostas. Uma boa API aponta o caminho do campo, a regra e uma mensagem estável. Não corrija cinco campos de uma vez. Mude um elemento, repita a requisição e registre o efeito.

Confirme Content-Type: application/json, nomes exatos das propriedades, tipos e formatos. O valor "10" é texto; 10 é número. null, campo ausente e string vazia podem ter significados diferentes. Datas devem seguir o contrato da API, inclusive fuso horário. Valores monetários merecem atenção especial: enviar 10,50 em JSON é inválido; 10.50 é número, enquanto "10.50" é string.

Em APIs que usam 400 para validação, o mesmo raciocínio vale. O código ajuda a localizar a camada, mas o contrato do serviço define detalhes.

500, 502, 503 e 504: prove o limite entre cliente e servidor

500 Internal Server Error é uma condição inesperada no servidor. Ainda assim, o cliente pode fornecer o dado que dispara o defeito. Antes de concluir que “é problema do backend”, reduza o corpo ao menor exemplo que ainda falha.

502 Bad Gateway indica que um gateway ou proxy recebeu uma resposta inválida do serviço acima. 503 Service Unavailable aponta indisponibilidade temporária, sobrecarga ou manutenção. 504 Gateway Timeout ocorre quando o gateway não recebeu a resposta upstream a tempo. Esses códigos sugerem lugares diferentes para procurar logs.

Legenda: o formato da resposta e o identificador de correlação ajudam a descobrir qual componente produziu o erro.

Repita a chamada com o mesmo corpo e com um corpo mínimo. Teste um endpoint de saúde apenas se ele for documentado. Compare horários, regiões e instâncias. Se uma em cada dez chamadas falha, pode haver uma instância ruim no balanceador. Se apenas entradas grandes falham, investigue limite de payload, memória e timeout.

Retentativas automáticas exigem cuidado. Não repita indiscriminadamente POST de criação, pois a primeira chamada pode ter sido concluída apesar da resposta perdida. Para operações seguras ou idempotentes, aplique espera crescente, limite de tentativas e aleatoriedade. Respeite Retry-After quando presente. O objetivo é aliviar uma falha temporária, não multiplicar a carga.

Diferencie erro da API, CORS e erro do seu próprio código

CORS é uma política aplicada pelo navegador. Uma requisição feita com curl não passa pelo mesmo bloqueio. Se curl recebe 200, mas o navegador impede o JavaScript de ler a resposta, compare Origin, preflight OPTIONS e cabeçalhos Access-Control-Allow-*. Isso não transforma CORS em “erro de internet”: o servidor respondeu, mas não autorizou aquela origem a expor a resposta ao script.

O inverso também acontece: o navegador mostra uma exceção em response.json(), porém o problema original é uma página HTML de proxy. Sempre inspecione status e Content-Type antes de interpretar o corpo:

async function chamarApi(url, opcoes = {}) {
  const resposta = await fetch(url, opcoes);
  const tipo = resposta.headers.get("content-type") || "";
  const corpo = tipo.includes("application/json")
    ? await resposta.json()
    : await resposta.text();

  if (!resposta.ok) {
    throw new Error(`HTTP ${resposta.status}: ${JSON.stringify(corpo)}`);
  }
  return corpo;
}

Esse exemplo é propositalmente pequeno. Em produção, não exiba ao usuário conteúdo interno ou dados sensíveis retornados pelo servidor. Registre uma mensagem segura e preserve o identificador técnico para suporte.

Use uma matriz de evidências em vez de tentativas aleatórias

Crie uma tabela com uma linha por experimento:

Teste	Identidade	Método e rota	Corpo	Resultado	Conclusão
A	sem token	GET /v1/clientes/10	—	401	autenticação exigida
B	token leitor	GET /v1/clientes/10	—	200	token e rota válidos
C	token leitor	PUT /v1/clientes/10	mínimo	403	falta permissão de escrita
D	token editor	PUT /v1/clientes/10	mínimo	200	autorização confirmada

Essa matriz elimina explicações incompatíveis. Se a mesma rota funciona com um usuário e falha com outro, DNS e deploy deixam de ser suspeitos principais. Se todos os usuários falham depois de uma versão nova, procure mudança de rota, gateway ou backend. Se somente um corpo específico gera 500, preserve esse caso como teste de regressão.

Mude uma variável por vez. Trocar token, rota, método e payload no mesmo teste impede saber qual alteração resolveu o problema. Dê um nome ao caso, guarde o comando sanitizado e anote o resultado esperado.

Checklist final para diagnosticar uma API em menos tempo

Antes de abrir um chamado, reúna:

• horário com fuso;
• ambiente e base URL;
• método e caminho, sem segredos;
• status HTTP;
• cabeçalhos relevantes de requisição e resposta;
• corpo mínimo que reproduz o erro;
• identificador de correlação;
• resultado esperado e resultado observado;
• frequência: sempre, intermitente ou apenas com um dado;
• comparação com uma chamada que funciona.

Nunca envie senha, cookie de sessão, token, chave de API ou dados pessoais no chamado. Substitua os valores, mas preserve o nome dos cabeçalhos e a estrutura do JSON. Se a falha envolve um registro real, crie um equivalente fictício quando possível.

A sequência mental é simples: primeiro confirme transporte; depois autenticação; em seguida autorização; então rota e método; por fim validação, estado e servidor. O código HTTP não entrega sozinho a causa raiz, mas diz onde começar. Quando você combina o status com uma requisição mínima e uma matriz de testes, o diagnóstico deixa de ser uma coleção de palpites.

Documentação primária e referências técnicas

• RFC 9110 — HTTP Semantics, seção de códigos de status
• MDN — Using the Fetch API
• curl — manual oficial
• OpenAPI Specification — Responses Object

Nota sobre a produção deste conteúdo

Rascunho inédito produzido com apoio de IA generativa a partir de uma lacuna identificada no acervo do IATechNerds. O procedimento foi estruturado com base na semântica oficial do HTTP, na documentação do fetch, no manual do curl e na especificação OpenAPI. Exemplos, links internos e recomendações precisam de revisão técnica humana antes da publicação. Nenhum endpoint real, credencial ou dado de usuário foi utilizado.

Camada extra: como tomar uma decisão melhor neste cenário

Em uso real, Como diagnosticar erros HTTP 401, 403, 404, 409, 422 e 500 sem chutar costuma envolver mais de uma camada. O ganho de qualidade aparece quando cada camada tem uma pergunta de verificação antes de qualquer mudança definitiva.

Uma API respondeu `401`, você trocou o token e recebeu `403`. Depois alterou a URL, chegou a um `404` e começou a mexer em tudo ao mesmo tempo. Esse é o caminho mais curto para transformar um erro simples em três problemas novos. Códigos HT A ideia central pode ser testada com quatro perguntas: o que foi observado, qual hipótese explica o sintoma, qual mudança é reversível e qual evidência prova que funcionou. Esse encadeamento evita que uma coincidência seja confundida com causa e torna o procedimento repetível por outra pessoa.

Qualidade de IA precisa de um teste, não de uma impressão

Para HTTP, API, debug, curl, escolha três tarefas representativas: uma simples, uma ambígua e uma em que a resposta possa ser conferida em fonte primária. Compare utilidade, rastreabilidade, privacidade, velocidade e quantidade de correção humana necessária. Uma resposta elegante não compensa uma citação inexistente ou uma conclusão que não pode ser reproduzida.

Separe ainda o que pode sair do dispositivo do que deve permanecer local. Dados públicos toleram fluxos diferentes de documentos internos, contratos, informações pessoais ou bases de clientes. A escolha entre processamento local e nuvem deve ser feita pelo risco do conteúdo, não apenas pela conveniência da interface.

Grade de avaliação prática

Critério	Pergunta	Evidência
Correção	A resposta bate com a fonte?	Checagem independente
Rastreabilidade	É possível localizar de onde veio?	Citação ou trecho verificável
Privacidade	Que dado sai do dispositivo?	Política e configuração
Esforço	Quanto trabalho humano resta?	Tempo de revisão

O ponto em que a IA deixa de ajudar

Se a tarefa exige precisão absoluta e a saída não pode ser validada, a automação deve ser limitada a apoio: localizar trechos, organizar opções ou preparar uma primeira versão. A decisão final precisa permanecer com alguém capaz de verificar a fonte e assumir a responsabilidade pelo resultado.

Checklist de fechamento

• Registre o estado inicial antes de alterar qualquer coisa.
• Faça uma mudança por rodada e anote o efeito.
• Teste um caso normal, um caso-limite e o cenário que originalmente falhou.
• Confirme que a solução continua válida depois de reiniciar, reabrir ou repetir o fluxo.
• Guarde uma forma de voltar ao estado anterior quando a alteração for destrutiva.

Esse método acrescenta profundidade sem transformar o artigo em teoria abstrata: o leitor entende por que cada passo existe e como reconhecer quando a situação exige uma decisão diferente.