Erros do Claude Code — como distinguir 401, 429, 529 e erros de instalação

Os erros do Claude Code se dividem em duas categorias principais, e a maioria dos resultados de busca aborda apenas uma delas. Erros do cliente durante a instalação e a execução são completamente diferentes, em causa e solução, dos erros da API retornados ao chamar o modelo. Este artigo se concentra na segunda categoria — 401, 429 e 529 — porque são os erros encontrados primeiro ao migrar de uma assinatura para uma chave de API.

As mensagens de erro aparecem em inglês em qualquer país. Abaixo, mantemos as mensagens exatamente como no original e escrevemos apenas as explicações em português.

Primeiro, divida a causa em três possibilidades em 30 segundos

Antes de alterar as configurações, envie uma solicitação diretamente ao endpoint. Essa única chamada distingue “problema do cliente / problema de autenticação / problema do servidor”.

# 오류가 클라이언트 문제인지 엔드포인트 문제인지 30초 만에 가르는 방법.
# 200이 돌아오면 키와 주소는 정상이고, 남은 문제는 Claude Code 설정입니다.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":16,
       "messages":[{"role":"user","content":"ping"}]}'

401 — o cabeçalho está errado, não a chave

Se o 401 continuar ocorrendo mesmo depois de emitir novas chaves várias vezes, suspeite do método de envio, não do valor. O Claude Code envia ANTHROPIC_AUTH_TOKEN no cabeçalho Authorization: Bearer e ANTHROPIC_API_KEY no cabeçalho x-api-key. Como os gateways geralmente esperam o primeiro formato, trocar as duas variáveis causa 401 mesmo com uma chave válida.

Também é comum que as duas variáveis permaneçam definidas simultaneamente. Remova uma delas, abra um novo shell e tente novamente. A diferença entre as variáveis está descrita em Diferença entre ANTHROPIC_AUTH_TOKEN e ANTHROPIC_API_KEY.

429 — dois 429 completamente diferentes

O número é o mesmo, mas as causas são completamente diferentes. Se você estiver usando uma assinatura, atingiu o limite da janela da sessão e não há alternativa além de esperar até que ela seja redefinida — mudar para um plano superior também não ajuda naquele momento. Se estiver usando uma chave de API, é um limite de solicitações por segundo ou de processamento de tokens; novas tentativas com recuo exponencial geralmente resolvem.

Você pode distinguir imediatamente os casos verificando se ANTHROPIC_BASE_URL está definido. Se estiver, você está usando uma chave, não uma assinatura. A estrutura dos limites de assinatura e as opções após excedê-los são abordadas em Preços do Claude Code.

529 overloaded_error — um erro que não é seu

529 significa que o servidor de modelos upstream está temporariamente sobrecarregado. O conteúdo da solicitação, a chave e o saldo não são a causa, portanto não é um erro que possa ser eliminado corrigindo as configurações. A resposta é tentar novamente, e o recuo exponencial tem uma taxa de sucesso muito maior do que uma nova tentativa imediata.

Ao usar um gateway com fallback automático, a solicitação é encaminhada por outro caminho quando um upstream retorna 529, reduzindo a frequência percebida. A explicação detalhada para leitores de língua inglesa está em Como lidar com 529 overloaded_error.

Continuar trabalhando depois de atingir o limite da assinatura

Se o 429 vier da assinatura, você pode transferir apenas essa sessão para uma chave em vez de esperar. Não é necessário cancelar a assinatura — enquanto as duas variáveis abaixo estiverem definidas, a cobrança será feita pela chave; ao removê-las, tudo volta ao normal.

# Claude Code를 구독 대신 API 키로 돌릴 때 쓰는 두 줄.
# 이 두 변수가 설정돼 있는 동안에는 구독 한도가 적용되지 않습니다.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

# Claude Code의 기본 모델과 opus·sonnet 별칭은 Anthropic의 최신 모델을 가리키므로,
# Kunavo가 아직 제공하지 않는 모델이 호출돼 404가 나지 않도록 모델을 고정합니다.
# sonnet 별칭이 부르는 Sonnet 5.5는 Kunavo가 제공하지 않아, 고정하지 않으면
# /model sonnet, opusplan의 실행 단계, sonnet으로 지정한 서브에이전트에서 404가 납니다.
# Opus 5.5는 Claude Code v2.1.280 이상이 필요합니다(이전 버전이면 claude update로 업데이트).
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5

# 백그라운드 작업을 가장 싼 모델로 보내는 한 줄 — 매 세션 효과가 있습니다.
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

As tarifas são lidas diretamente do catálogo: Claude Sonnet 5 custa $1.40 / $7.00 por 1M de tokens, e Claude Haiku 4.5 custa $0.70 / $3.50. O valor é descontado do saldo pré-pago, portanto não há cobrança nos meses sem uso. Os meios de pagamento e o registro de cartões nacionais estão descritos em Preços e pagamentos da Claude API.

Os erros da etapa de instalação são separados

Problemas de instalação geralmente são causados pela versão do Node.js ou por permissões de instalação global e pertencem a uma categoria diferente dos três erros acima. Primeiro, confirme se claude --version é exibido corretamente. Se for, a instalação terminou; problemas posteriores estão relacionados à autenticação ou à rede. Misturar as duas categorias é a forma que mais consome tempo.

Perguntas frequentes