Referência de erros: Claude Code e Codex em uma API de terceiros

Como usar esta página

Não comece procurando o texto do erro. Comece descobrindo qual camada falhou. Quase todo erro de cliente de IA vem de uma destas cinco:

1. Rede: a requisição nunca saiu da sua máquina
2. Autenticação: chegou, mas a key foi rejeitada
3. Protocolo: a key estava certa, o caminho ou o formato não
4. Modelo: o protocolo funcionou, o modelo não existe
5. Contexto: o modelo está rodando, a entrada é longa demais

Separar em camadas importa porque cada uma tem uma correção completamente diferente, e o texto do erro raramente diz em qual você está.

Diagnóstico pelo status HTTP

Estes comandos verificam a lista de modelos e três protocolos, mostrando o status HTTP de cada solicitação:

Defina sua própria API key do KimiSeek no mesmo terminal que executará curl, substituindo o valor de exemplo. Uma credencial configurada no cliente não preenche automaticamente esta variável do shell:

# Replace the placeholder with your own key from the dashboard.
export KIMISEEK_API_KEY="ks-your-key"

# Inspect each HTTP status and error body; a model list does not prove sufficient balance.
# 1. Is the key valid at all? (lists models)
curl -sS --max-time 30 -w '\nHTTP %{http_code} /v1/models\n' https://api.kimiseek.app/v1/models \
  -H "Authorization: Bearer ${KIMISEEK_API_KEY:?Set KIMISEEK_API_KEY before running this command}"

# 2. OpenAI Chat Completions
curl -sS --max-time 30 -w '\nHTTP %{http_code} /v1/chat/completions\n' https://api.kimiseek.app/v1/chat/completions \
  -H "Authorization: Bearer ${KIMISEEK_API_KEY:?Set KIMISEEK_API_KEY before running this command}" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-pro-0813","messages":[{"role":"user","content":"ping"}],"max_tokens":8}'

# 3. Anthropic Messages (the protocol Claude Code speaks)
curl -sS --max-time 30 -w '\nHTTP %{http_code} /v1/messages\n' https://api.kimiseek.app/v1/messages \
  -H "x-api-key: ${KIMISEEK_API_KEY:?Set KIMISEEK_API_KEY before running this command}" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-pro-0813","max_tokens":8,"messages":[{"role":"user","content":"ping"}]}'

# 4. OpenAI Responses (the protocol Codex speaks)
curl -sS --max-time 30 -w '\nHTTP %{http_code} /v1/responses\n' https://api.kimiseek.app/v1/responses \
  -H "Authorization: Bearer ${KIMISEEK_API_KEY:?Set KIMISEEK_API_KEY before running this command}" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-pro-0813","input":"ping","max_output_tokens":16}'

Leia o status HTTP após cada resposta e os campos error.code, error.type e message do corpo. A etapa que falha não determina o suporte ao protocolo. Uma lista de modelos com 200 valida a chave, não o saldo: uma conta sem saldo pode receber 200 na etapa 1 e 402 na etapa 2.

Lado do Claude Code

Sem credenciais

Invalid API key · Please run /login

Isso significa que o Claude Code não encontrou credencial nenhuma. Verifique se ANTHROPIC_AUTH_TOKEN está definido no shell que iniciou o cliente — o erro clássico é exportar em um terminal e abrir o cliente em outro.

401 não autorizado

API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"invalid api key"}}

Causas, em ordem de probabilidade:

1. A key foi copiada com espaço ou quebra de linha no fim
2. A key foi revogada ou a cota acabou
3. ANTHROPIC_API_KEY está definida mas vazia, então o cliente cai para uma sessão de login

403 forbidden

API Error: 403 {"type":"error","error":{"type":"forbidden","message":"invalid x-api-key"}}

Indo direto, isso costuma significar key inválida. Passando por um gateway, a causa mais comum é um header escrito de outro jeito: alguns gateways só aceitam Authorization: Bearer, outros só x-api-key. O KimiSeek aceita os dois, mas se houver outro proxy no meio o header pode ser reescrito.

model not found

API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"model: deepseek-v4-flash-0731 not found"}}

Duas possibilidades: nome de modelo escrito errado, ou modelo descontinuado. Um id descontinuado continua devolvendo not found em vez de avisar que foi descontinuado, e é essa a armadilha que mais custa tempo aqui — você acaba auditando configuração quando a resposta real é que o modelo foi substituído.

Substitua por um id real da página de modelos.

O stream corta no meio

API Error: stream disconnected before completion: stream closed before completion

Uma conexão de streaming foi cortada no meio. Verifique nesta ordem:

1. Se um proxy HTTP local (HTTPS_PROXY) está interceptando
2. Se a rede corporativa dá timeout em respostas longas
3. Se um limite por requisição do servidor disparou

O tempo limite da requisição ao upstream é de 600 segundos em /v1/messages (Claude Code) e de 175 segundos em /v1/responses (Codex). O cliente ou um proxy intermediário pode encerrar a conexão antes disso; confira o endpoint utilizado e os detalhes do erro.

Estouro de contexto

API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"prompt is too long: 210000 tokens > 200000 maximum"}}

Repare que o 200000 aqui é o limite do cliente ou do modelo, não necessariamente o que você esperava. No DeepSeek V4 Pro o limite real é 1M, então ver 200000 significa que a requisição não chegou ao modelo que você pensa, ou que o cliente truncou na especificação do Claude.

Lado do Codex

401 Missing bearer

■ unexpected status 401 Unauthorized: Missing bearer

env_key em config.toml é só um nome de variável; o valor precisa estar no ambiente. Este erro é "você nomeou a variável, mas ela está vazia".

404 Not Found

■ unexpected status 404 Not Found

Oito em cada dez vezes falta /v1 no base_url. O Codex monta base_url + "/responses", então sem /v1 ele bate numa página web.

Depois de verificar base_url, veja também se o corpo informa que o modelo não foi encontrado. Se o gateway realmente não oferece /v1/responses, use um gateway ou uma camada de conversão compatível; o Codex atual rejeita wire_api = "chat". Veja o guia do Codex.

Interrupção do stream

■ stream disconnected before completion

Mesmo problema de streaming do Claude Code, mas o Codex é mais sensível porque o loop de execução dele depende de um fluxo de eventos completo. Em rede instável, troque de rede em vez de tentar de novo.

Duas falhas de rede típicas

fetch failed
ECONNREFUSED 127.0.0.1:7890

fetch failed é o erro genérico de rede do Node e não carrega informação nenhuma sozinho. Para ver a causa concreta é preciso olhar a linha do ECONNREFUSED — se ela aponta para uma porta local como 127.0.0.1:7890, um proxy local assumiu a requisição e o proxy não está rodando ou as regras dele estão erradas.

Esta é a falha mais vezes diagnosticada errado como "o gateway caiu". O teste: se o curl funciona e o cliente não, o ambiente do shell do cliente é diferente do shell do curl.

Mesmo erro, causa diferente

É o modelo mental que mais importa quando há um gateway no meio:

O que incluir quando pedir ajuda

Quatro coisas, todas, ou ninguém consegue diagnosticar:

1. A linha completa do erro, não uma captura de tela recortada
2. O resultado do probe de curl por camadas — qual dos quatro passos falhou
3. As versões dos clientes (claude --version, codex --version)
4. O id do modelo e o Base URL em uso, com a key mascarada

Verificação

• Verificado em: 2026-10-26
• Os exemplos ajudam a localizar a falha; as mensagens podem variar conforme a versão do cliente. Informe a versão instalada ao relatar um problema. A configuração do Codex foi verificada com 0.154.0.