Claude Code erro 404: URL, rota ou modelo?

Resposta rápida

Um 404 normalmente significa que a requisição chegou a um servidor, mas o caminho, o recurso ou o modelo pedido não foi encontrado. Ele não é o mesmo que 401: uma credencial inválida deve ser corrigida na chave ou no cabeçalho; um 404 exige revisar a URL base, o caminho da rota e a existência do modelo no gateway.

No Claude Code, a causa mais comum é uma URL base construída com um sufixo que o cliente já adiciona por conta própria. Outras causas são caminho de gateway incorreto, header removido por proxy e modelo indisponível para a credencial.

Primeiro: separe 401 de 404

Se você alterou duas coisas ao mesmo tempo — base URL e credencial — volte ao último estado funcional e mude uma variável por vez.

As cinco causas mais comuns

1. /v1 duplicado na Base URL

O cliente deve receber apenas a raiz do gateway definida pelo provedor. Não acrescente automaticamente um prefixo que o Claude Code já monta na chamada. Para a MandAPI, a base documentada é:

https://api.mandapi.com

Se a base terminar em /v1 e o cliente também adicionar /v1 ao caminho, a rota final pode ficar duplicada.

2. Rota de gateway incorreta

Confirme o caminho exigido pelo gateway e pelo cliente. Não invente um sufixo “compatível” apenas porque outra ferramenta usa um caminho parecido. A documentação do Claude Code descreve a configuração de gateways de terceiros; a MandAPI documenta a base e o formato de autenticação aceitos.

3. Modelo não disponível

Um 404 também pode aparecer quando o identificador do modelo não existe no catálogo acessível àquela credencial. Liste os modelos e use o id exato:

curl -sS https://api.mandapi.com/v1/models \
  -H "Authorization: Bearer $MANDAPI_API_KEY"

Não copie um nome de modelo de um artigo antigo. O catálogo muda e o caminho correto é validar o id atual.

4. Header de autenticação removido no meio do caminho

Proxies e configurações de rede podem remover ou reescrever headers. Um gateway pode devolver 404 quando o header necessário não chega ao destino, especialmente se a rota for tratada como recurso inexistente. Faça um teste direto contra o endpoint antes de colocar o Claude Code na frente.

5. Arquivo de configuração errado

O Claude Code lê configurações em níveis diferentes. Se você editar um projeto, abrir outro terminal ou manter uma chave antiga em ANTHROPIC_API_KEY, a sessão pode usar uma configuração diferente da que você revisou.

Configuração de referência

Use o arquivo de usuário, não um arquivo de projeto que vai para o Git:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.mandapi.com",
    "ANTHROPIC_AUTH_TOKEN": "COLE_SUA_CHAVE_MANDAPI_AQUI"
  }
}

ANTHROPIC_AUTH_TOKEN e ANTHROPIC_API_KEY não são intercambiáveis em todos os gateways. O primeiro é enviado como Authorization: Bearer; o segundo usa x-api-key. Use o método documentado para o seu gateway e remova credenciais antigas que possam competir.

Teste direto antes do Claude Code

No macOS, Linux ou WSL:

export ANTHROPIC_BASE_URL="https://api.mandapi.com"
export ANTHROPIC_AUTH_TOKEN="$MANDAPI_API_KEY"
export MANDAPI_MODEL="COLE_UM_ID_LISTADO_PELA_API"

curl -sS -D /tmp/mandapi-headers.txt \
  -o /tmp/mandapi-body.json \
  -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d "{\"model\":\"$MANDAPI_MODEL\",\"max_tokens\":1,\"messages\":[{\"role\":\"user\",\"content\":\".\"}]}"

sed -n '1,20p' /tmp/mandapi-headers.txt
cat /tmp/mandapi-body.json

No PowerShell:

$env:ANTHROPIC_BASE_URL = "https://api.mandapi.com"
$env:ANTHROPIC_AUTH_TOKEN = $env:MANDAPI_API_KEY
$env:MANDAPI_MODEL = "COLE_UM_ID_LISTADO_PELA_API"

Invoke-WebRequest -Method Post `
  -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
  -Headers @{
    Authorization = "Bearer $env:ANTHROPIC_AUTH_TOKEN"
    "anthropic-version" = "2023-06-01"
  } `
  -ContentType "application/json" `
  -Body "{`"model`":`"$env:MANDAPI_MODEL`",`"max_tokens`":1,`"messages`":[{`"role`":`"user`",`"content`":`".`"}]}"

Se a resposta indicar modelo desconhecido, a URL e a autenticação já chegaram ao gateway; corrija o model. Se continuar 404, compare a Base URL e o caminho da rota antes de trocar a chave.

Teste ponta a ponta

Depois que o endpoint direto passar, teste o Claude Code em um projeto isolado:

claude -p "Responda apenas: MandAPI conectada"

A resposta pode variar; o que importa é não receber 401, 403 ou 404. Em uma sessão interativa, use os comandos de diagnóstico do próprio Claude Code para conferir a base e o método de autenticação carregados.

O que não fazer

• Colocar /v1 manualmente na ANTHROPIC_BASE_URL.
• Misturar ANTHROPIC_AUTH_TOKEN e ANTHROPIC_API_KEY na mesma sessão.
• Testar com um modelo inventado ou retirado de uma lista velha.
• Guardar a chave em arquivo versionado.
• Concluir que “o gateway não funciona” sem validar a rota direta.

Próximos passos

• Configure a base em Como configurar ANTHROPIC_BASE_URL.
• Confira a diferença entre tokens em ANTHROPIC_AUTH_TOKEN ou ANTHROPIC_API_KEY.
• Faça o teste completo em Como testar a conexão da API.
• Consulte o envelope de erro em Erros da API.

Fontes

• Claude Code — Connect to an LLM gateway: https://code.claude.com/docs/en/llm-gateway-connect
• Anthropic — API errors: https://platform.claude.com/docs/en/api/errors
• MandAPI — Erros da API: https://mandapi.com/docs/errors

Última verificação editorial: 20 de setembro de 2026. O comportamento de gateways pode variar; valide a rota e o catálogo atuais antes de alterar produção.