---
title: "Códigos de erro e solução de problemas"
description: "Causas e soluções ao encontrar 401, 404, 429, 529, 5xx, timeouts e erros do Claude Code ao chamar a 1折AI."
headingIds: {"Ordem de verificação":"section-1","Tabela rápida de códigos de erro":"section-2","Respostas reais testadas":"section-3","Solução de problemas por sintoma":"section-4","401 / Invalid token":"section-5","404 / Invalid URL":"section-6","403 / error code: 1010":"section-7","429 Muitas requisições":"section-8","529 / overloaded_error":"section-9","Timeout, desconexão no meio do streaming":"section-10","Claude Code: entra direto na tela de login":"section-11","Claude Code: Extra inputs are not permitted / context_management retorna 400":"section-12","Saldo suficiente, mas as chamadas falham":"section-13","Retentativas limitadas e modelo de feedback":"section-14","Ainda não resolvido":"section-15"}
---

<aside className="docs-publication" data-pagefind-ignore>

Documentação mantida por [1ZheAI](https://1zheai.com/en/editorial/#publisher). [Fontes e correções](https://1zheai.com/en/editorial/).

Encontrou um erro? [Contate o suporte](mailto:support@1zheai.com) com o endereço da página e uma descrição. Não envie chaves de API ou credenciais de conta.

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

## Ordem de verificação

1. **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](/pt/docs/base-url/).
2. **Chave de API (API key)**: está completa (sem espaços ou quebras de linha extras), foi excluída ou está preenchida no campo correto.
3. **Saldo**: o saldo no console é suficiente.
4. **ID do modelo**: está idêntico ao dos [modelos suportados](/pt/docs/models/).
5. **Rede**: desative o proxy e tente conectar diretamente novamente.
6. **Ainda sem solução**: gere uma reprodução mínima com curl (veja abaixo) e nos envie a resposta e o tempo.

```bash title="最小复现"
curl -i https://1zheai.com/v1/messages \
  -H "x-api-key: sk-你的Key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -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 support@1zheai.com |
| 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](https://platform.claude.com/docs/en/api/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`.

<CodeGroup>
```json title="401 API 密钥无效、禁用、过期或额度用完"
{"error":{"message":"Invalid token (request id: 202610150244355244812608268d9d6T1pY7T84)","type":"authentication_error"},"type":"error"}
```
```json title="403 账户余额不足"
{"error":{"type":"billing_error","message":"Insufficient user quota, remaining quota: ＄0.000000 (request id: 202610150244418753787808268d9d67YNhvwXd)"},"type":"error"}
```
```json title="403 API 密钥没开通该模型"
{"error":{"message":"This token has no access to model claude-sonnet-4-6 (request id: 202610150244377127013108268d9d6yCiFOxJA)","type":"permission_error"},"type":"error"}
```
```json title="403 IP 不在白名单"
{"error":{"message":"Your IP address is not on this token's allowlist (request id: 202610150244409011371208268d9d63tJvd5GD)","type":"permission_error"},"type":"error"}
```
```json title="400 上游参数错误"
{"error":{"type":"invalid_request_error","message":"messages: Unexpected role \"robot\". Allowed roles are \"user\", \"assistant\" or \"system\" (request id: 202610150245008404167198268d9d6sajV9TX3)"},"type":"error"}
```
```json title="404 路径不存在"
{"error":{"message":"Invalid URL (POST /v1/nonexistent)","type":"invalid_request_error","param":"","code":""}}
```
</CodeGroup>

A explicação do 404 quando o modelo não existe ou está indisponível está em [modelos suportados](/pt/docs/models/). 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](/pt/docs/models/). 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](/pt/docs/quickstart-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):

```bash
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](/pt/docs/retries/).

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

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

## Ainda não resolvido

Envie um e-mail para support@1zheai.com 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).