Resolver erros 401, 403, 429 e 5xx

Doze tipos concretos de falha que vemos semana após semana. Sintoma → causa → correção em uma linha.

Principais perguntas

Preciso fazer login no Claude Code? E quanto ao 401 e ao “Auth conflict”?

Não. A chave da OneProvider funciona sem uma conta Claude. No Claude Code, defina ANTHROPIC_BASE_URL e ANTHROPIC_AUTH_TOKEN (a chave é enviada como Authorization: Bearer). Essa variável tem precedência sobre um login salvo e sobre as outras variáveis, e não exige confirmação. Nosso gateway também aceita ANTHROPIC_API_KEY (cabeçalho x-api-key), mas no modo interativo o Claude Code pede uma vez para você aprovar essa chave e ignora em silêncio uma chave recusada (reative em /config → Use custom API key).

Se aparecer a tela de login, 401 Invalid API key ou Auth conflict, siga passo a passo:

1. Execute /status: ele deve mostrar o Anthropic base URL da OneProvider e uma linha Auth token ou API key com o nome da sua variável. Uma linha Login method com uma conta claude.ai significa que a variável não chegou à sessão.
2. Auth conflict (um login claude.ai e uma chave ao mesmo tempo): execute /logout; as suas variáveis permanecem.
3. 401 Invalid API key: um ANTHROPIC_AUTH_TOKEN alheio (um token de outro serviço) sobrepõe a sua chave, ou o valor tem uma aspa ou um espaço perdido. Defina-o como a chave completa da OneProvider, sem aspas.
4. A tela de login continua mesmo com as variáveis no .claude/settings.json de um projeto: esse bloco é lido depois da configuração do primeiro uso, então coloque as variáveis no seu shell ou em ~/.claude/settings.json.

# macOS / Linux: what is actually set
env | grep -E 'ANTHROPIC_(BASE_URL|AUTH_TOKEN|API_KEY)' | sed -E 's/(sk-.{4}).*/\1.../'
grep -nE 'ANTHROPIC_(AUTH_TOKEN|API_KEY)' ~/.zshrc ~/.bashrc 2>/dev/null

Preciso fazer login no ChatGPT para usar a CLI do Codex?

Não. O Codex funciona só com a chave quando o provedor oneprovider em ~/.codex/config.toml está ativo (env_key = "ONEPROVIDER_API_KEY"). Um pedido de login no ChatGPT ou "You've hit your usage limit" significa que o provedor não está ativo e a requisição foi para o ChatGPT.

Confira nesta ordem: as linhas model_provider e model estão logo no começo do arquivo, acima de qualquer [table]; o Codex foi totalmente reiniciado e a tarefa é nova; a chave foi exportada no mesmo terminal:

codex logout
export ONEPROVIDER_API_KEY="sk-..."
# quick test without editing the file:
codex -c model_provider=oneprovider

O passo a passo completo está na página Codex (OpenAI) .

Preciso de VPN? Há restrições regionais?

Não precisa de VPN — a OneProvider não tem restrições regionais. O endpoint api.oneprovider.dev é acessível no mundo todo e não bloqueia tráfego por região.

Pior: VPNs e proxies VLESS muitas vezes quebram a conexão com a API de duas maneiras:

• O streaming SSE é armazenado em buffer dentro do proxy — o stream é cortado no meio de um token.
• A negociação HTTP/2 + ALPN falha nos saltos do relay — o cliente vê connection reset.

Se você vê streams cortados, connection reset ou timeouts aleatórios, desative a VPN / o proxy VLESS e tente de novo. Do nosso lado, não armazenamos streams em buffer.

Erro de parse de JSON na configuração (ou um 429)

A causa mais comum são as aspas “inteligentes” (“ ”) na sua configuração JSON. Elas aparecem quando você copia de um mensageiro, do Notion, do Google Docs ou de um navegador que troca as aspas ASCII por tipográficas. Os parsers de JSON só aceitam as aspas ASCII simples ".

Às vezes uma configuração quebrada não aparece como “JSON parse error”, e sim como um 429: o cliente trata a falta de resposta como um limite de requisições. A correção é a mesma:

• Troque todo “ ” por " à mão.
• Copie as configurações direto desta documentação — aqui as aspas já estão corretas.
• Valide com cat -v config.json ou jq . config.json — os dois apontam o byte inválido.

# Quick check: jq fails on the first smart quote
jq . ~/.claude/settings.json
# Auto-replace smart quotes with straight quotes
sed -i.bak $'s/[\u201c\u201d]/"/g' ~/.claude/settings.json

Matriz de sintomas

Comandos de diagnóstico em uma linha

Se a matriz de sintomas não cobriu o seu caso, reúna estas três evidências:

# 1. Confirm reach + auth
curl -sS -o /dev/null -w "HTTP %{http_code} total %{time_total}s\n" \
https://api.oneprovider.dev/v1/models -H "x-api-key: $ANTHROPIC_API_KEY"
# 2. Reproduce the failing call with -v (verbose headers)
curl -sv https://api.oneprovider.dev/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-sonnet-5-5","max_tokens":32,"messages":[{"role":"user","content":"hi"}]}'
# 3. Check your current balance (also shown in the cabinet: the @oneprovider_robot bot or app.oneprovider.dev)
curl -s https://api.oneprovider.dev/v1/dashboard/balance \
-H "Authorization: Bearer $ANTHROPIC_API_KEY"

Quando escalar

Envie as três saídas acima + os 8 primeiros caracteres da sua chave + um carimbo de data e hora em UTC para @Oneproviderhelpbot . Isso basta para encontrarmos a sua requisição nos nossos logs em poucos minutos. Veja Falar com o suporte para saber o que não precisamos (e nunca pedimos).