Códigos de erro e solução de problemas

Causas e soluções ao encontrar 401, 404, 429, 529, 5xx, timeouts e erros do Claude Code ao chamar a 1折AI.

Percorra a lista abaixo na ordem indicada; a maioria dos problemas é encontrada nos três primeiros passos.

Ordem de verificação

Endereço: ferramentas da série Anthropic devem usar https://1zheai.com, ferramentas da série OpenAI devem usar https://1zheai.com/v1. Veja Base URL e autenticação.
Chave de API (API key): está completa (sem espaços ou quebras de linha extras), foi excluída ou está preenchida no campo correto.
Saldo: o saldo no console é suficiente.
ID do modelo: está idêntico ao dos modelos suportados.
Rede: desative o proxy e tente conectar diretamente novamente.
Ainda sem solução: gere uma reprodução mínima com curl (veja abaixo) e nos envie a resposta e o tempo.

1
curl -i https://1zheai.com/v1/messages \
2
  -H "x-api-key: sk-你的Key" \
3
  -H "anthropic-version: 2023-06-01" \
4
  -H "content-type: application/json" \
5
  -d '{"model":"claude-sonnet-5-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

-i imprime o código de status junto com os cabeçalhos de resposta, o que é muito útil na solução de problemas.

Tabela rápida de códigos de erro

Código de status	Causas comuns	O que fazer
400	Problema no corpo da requisição: nome de parâmetro incorreto, tipo de campo incorreto, `max_tokens` acima do limite do modelo, campo beta não reconhecido pelo upstream	Verifique o campo indicado em `message`; para o caso do Claude Code, veja “Extra inputs are not permitted” abaixo
401	Chave de API inválida, excluída, desabilitada, expirada, cota própria esgotada, ou ausente/colocada no cabeçalho errado	Todas as respostas são `Invalid token`; verifique item por item; no uso nativo Anthropic, use `x-api-key` ou `Authorization: Bearer`
403	Saldo da conta insuficiente (`billing_error` / `insufficient_quota`); esta chave de API não tem acesso ao modelo; o IP da requisição não está na lista branca desta chave de API (ambos retornam `permission_error`)	Recarregue ou edite as restrições de modelo e a lista branca de IP desta chave de API na página “Chaves de API”
404	Caminho incorreto, ou modelo inexistente / indisponível no momento	`Invalid URL` verifique o endereço; `not_found_error` / `model_not_found` verifique o ID do modelo e a lista de disponibilidade
413	Corpo da requisição muito grande	Reduza o conteúdo enviado de uma vez; divida arquivos grandes em partes
429	Limitação temporária de taxa do upstream. Atualmente não aplicamos limites de taxa às chaves de API	Tente novamente mais tarde; em tarefas em lote, use backoff exponencial
503	O modelo existe, mas não há serviço upstream saudável disponível no momento, ou falha temporária do serviço	Tente novamente mais tarde; em falhas persistentes, entre em contato com o suporte informando o ID da requisição
500 / 502	Falha temporária do gateway ou do upstream	Tente novamente mais tarde; em falhas persistentes, envie e-mail para [email protected]
504	Timeout da requisição	Use streaming para saídas longas; aumente o timeout do cliente
529	Sobrecarga do upstream Anthropic (`overloaded_error`)	Aguarde alguns segundos e tente novamente, ou troque temporariamente de modelo

O significado completo dos tipos de erro oficiais da Anthropic (invalid_request_error, authentication_error, rate_limit_error, overloaded_error, etc.) está na documentação oficial de Errors.

Erros retornados pelo upstream são repassados com o código de status e message inalterados, e message recebe o request id desta requisição no final. Ao usar /v1/messages, a estrutura externa é a {"type":"error","error":{...}} oficial, e error.type é preenchido com o tipo oficial conforme o código de status; ao usar /v1/chat/completions, é a estrutura {"error":{...}} da OpenAI.

Respostas reais testadas

Abaixo estão respostas reais testadas em 2026-10-15 para /v1/messages. Ao usar /v1/chat/completions, o conteúdo é o mesmo, sem "type":"error" na camada externa, e error contém um campo adicional code.

{"error":{"message":"Invalid token (request id: 202610150244355244812608268d9d6T1pY7T84)","type":"authentication_error"},"type":"error"}

{"error":{"type":"billing_error","message":"Insufficient user quota, remaining quota: ＄0.000000 (request id: 202610150244418753787808268d9d67YNhvwXd)"},"type":"error"}

{"error":{"message":"This token has no access to model claude-sonnet-4-6 (request id: 202610150244377127013108268d9d6yCiFOxJA)","type":"permission_error"},"type":"error"}

{"error":{"message":"Your IP address is not on this token's allowlist (request id: 202610150244409011371208268d9d63tJvd5GD)","type":"permission_error"},"type":"error"}

{"error":{"type":"invalid_request_error","message":"messages: Unexpected role \"robot\". Allowed roles are \"user\", \"assistant\" or \"system\" (request id: 202610150245008404167198268d9d6sajV9TX3)"},"type":"error"}

{"error":{"message":"Invalid URL (POST /v1/nonexistent)","type":"invalid_request_error","param":"","code":""}}

A explicação do 404 quando o modelo não existe ou está indisponível está em modelos suportados. O request id na resposta corresponde a esta requisição; inclua-o ao reportar problemas.

Solução de problemas por sintoma

401 / Invalid token

A chave de API foi copiada com espaços ou quebras de linha extras; copie novamente.
A chave de API foi excluída ou desabilitada no console, ou expirou, ou a cota própria foi esgotada. Em todos esses casos, a resposta é a mesma: Invalid token.
No Claude Code, ANTHROPIC_API_KEY e ANTHROPIC_AUTH_TOKEN estão definidos ao mesmo tempo e um deles é um valor antigo: mantenha apenas um; recomenda-se ANTHROPIC_AUTH_TOKEN.
O env do settings.json sobrescreve variáveis de mesmo nome exportadas no terminal; se alterar a variável do terminal não tiver efeito, verifique ~/.claude/settings.json.

404 / Invalid URL

Verifique primeiro o tipo de erro: not_found_error ou model_not_found exige verificar o ID do modelo e a lista de disponibilidade. Já Invalid URL exige verificar /v1: OpenAI SDK, Cursor e Cline (OpenAI Compatible) devem preencher até https://1zheai.com/v1; Claude Code e Anthropic SDK devem preencher apenas https://1zheai.com; preencher /v1 resultará em /v1/v1/messages.

403 / error code: 1010

Se a resposta contiver apenas a linha error code: 1010 e nenhum JSON, a requisição foi bloqueada antes de chegar ao gateway. É conhecido que enviar requisições diretamente com a biblioteca padrão do Python urllib causa isso (o User-Agent padrão dela é Python-urllib/3.x). Adicione um User-Agent próprio nos cabeçalhos da requisição, ou use o SDK oficial, requests, httpx.

429 Muitas requisições

Atualmente não aplicamos limites de taxa às chaves de API. Ao receber 429, normalmente é alta carga no upstream; tente novamente mais tarde. Para tarefas em lote, recomenda-se backoff exponencial: após uma falha, aguarde um período antes de tentar novamente, dobrando o tempo de espera a cada vez, e controle a concorrência com uma fila própria.

529 / overloaded_error

O upstream Anthropic está temporariamente sobrecarregado; não tem relação com sua chave de API ou saldo. Aguarde alguns segundos e tente novamente; se estiver com pressa, troque temporariamente para outro modelo da mesma série.

Timeout, desconexão no meio do streaming

Para respostas longas, use sempre streaming ("stream": true), que é menos propenso a ser cortado por dispositivos de rede intermediários.
No Claude Code, use API_TIMEOUT_MS para aumentar o timeout; o padrão é 600000 (10 minutos).
Se estiver usando proxy, desative-o e tente uma vez; muitas desconexões de stream vêm de nós de proxy.

Claude Code: entra direto na tela de login

Isso significa que o Claude Code não encontrou sua chave de API. Execute /status no Claude Code e verifique as linhas de base URL e origem das credenciais; se estiverem vazias, volte para integração com Claude Code e verifique as variáveis de ambiente ou settings.json.

Claude Code: Extra inputs are not permitted / context_management retorna 400

O Claude Code envia alguns campos beta experimentais nas requisições; um upstream estrito que não os reconhece retornará 400. Defina as variáveis de ambiente abaixo para desativá-las (da documentação oficial de LLM gateway do Claude Code):

1
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

Saldo suficiente, mas as chamadas falham

Se apenas um modelo falhar, pode ser que ele esteja temporariamente indisponível, o ID esteja escrito incorretamente, ou esta chave de API tenha restrição de modelo (403 This token has no access to model …).
Se todos falharem com 401, verifique se esta chave de API tem limite de cota definido e já esgotado, ou se expirou. Isso pode ser visto nas colunas “Cota ($)” e “Expira em” da página “Chaves de API”.
Para outros casos, consulte a tabela de códigos de erro acima.

Retentativas limitadas e modelo de feedback

Não use loops infinitos para mascarar erros de configuração. Para timeouts do SDK, número de retentativas automáticas e backoff, consulte timeout e retentativas.

Ao contatar o suporte, pode copiar o modelo abaixo, removendo chaves, cabeçalhos de autenticação e conteúdo pessoal antes de enviar:

1
发生时间与时区：
2
客户端及版本：
3
请求方法与完整路径：
4
模型 ID：
5
HTTP 状态码：
6
request id（如有）：
7
脱敏后的错误正文：
8
最小请求能否复现：
9
是否使用代理 / 是否仅某个模型失败：

Ainda não resolvido

Envie um e-mail para [email protected] com o horário, o ID do modelo, a ferramenta e a versão usadas, e a saída completa de curl -i (remova a chave de API).