Risolvere gli errori 401, 403, 429 e 5xx

Dodici casi concreti di errore che vediamo ogni settimana. Sintomo → causa → correzione in una riga.

Domande frequenti

Devo accedere a Claude Code? E il 401 e «Auth conflict»?

No. La chiave OneProvider funziona senza un account Claude. Per Claude Code imposta ANTHROPIC_BASE_URL e ANTHROPIC_AUTH_TOKEN (la chiave viene inviata come Authorization: Bearer). Questa variabile ha la precedenza su un accesso salvato e sulle altre variabili, e non mostra alcuna richiesta di conferma. Il nostro gateway accetta anche ANTHROPIC_API_KEY (header x-api-key), ma in modalità interattiva Claude Code ti chiede una volta di approvare una chiave del genere e ignora in silenzio quella rifiutata (riattivala in /config → Use custom API key).

Se vedi la schermata di accesso, 401 Invalid API key o Auth conflict, procedi passo per passo:

1. Esegui /status: dovrebbe mostrare la Anthropic base URL di OneProvider e una riga Auth token o API key con il nome della tua variabile. Una riga Login method con un account claude.ai significa che la variabile non è arrivata alla sessione.
2. Auth conflict (sia un accesso claude.ai sia una chiave): esegui /logout; le tue variabili restano.
3. 401 Invalid API key: un ANTHROPIC_AUTH_TOKEN estraneo (un token di un altro servizio) sovrascrive la tua chiave, oppure il valore ha una virgoletta o uno spazio di troppo. Impostalo con la chiave OneProvider completa, senza virgolette.
4. La schermata di accesso resta anche se le variabili sono nel .claude/settings.json di un progetto: quel blocco viene letto dopo la configurazione iniziale, quindi metti le variabili nella tua shell o in ~/.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

Devo accedere a ChatGPT per usare Codex CLI?

No. Codex funziona con la sola chiave quando il provider oneprovider in ~/.codex/config.toml è attivo (env_key = "ONEPROVIDER_API_KEY"). Una richiesta di accesso a ChatGPT o il messaggio "You've hit your usage limit" significa che il provider non è attivo e la richiesta è andata a ChatGPT.

Controlla in quest'ordine: le righe model_provider e model sono in cima al file, sopra qualsiasi [table]; Codex è stato riavviato del tutto e l'attività è nuova; la chiave è esportata nello stesso terminale:

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

La guida completa è nella pagina Codex (OpenAI) .

Mi serve una VPN? Ci sono restrizioni regionali?

Non serve nessuna VPN: OneProvider non ha restrizioni regionali. L'endpoint api.oneprovider.dev è raggiungibile da tutto il mondo e non blocca il traffico per area geografica.

Anzi, le VPN e i proxy VLESS spesso rompono la connessione all'API in due modi:

• Lo streaming SSE viene messo in buffer dentro il proxy: lo stream si interrompe a metà token.
• La negoziazione HTTP/2 + ALPN si rompe nei salti dei relay: il client vede connection reset.

Se vedi stream interrotti, connection reset o timeout casuali, disattiva la VPN / il proxy VLESS e riprova. Noi non mettiamo in buffer gli stream dalla nostra parte.

Errore di parsing JSON nella configurazione (o un 429)

La causa più comune sono le virgolette «tipografiche» (“ ”) nella tua configurazione JSON. Compaiono quando copi da un messenger, da Notion, da Google Docs o da un browser che sostituisce le virgolette ASCII con quelle tipografiche. I parser JSON accettano solo le semplici virgolette ASCII ".

A volte una configurazione rotta non si manifesta come «JSON parse error» ma come 429: il client scambia la risposta mancante per un limite di frequenza. Stessa soluzione:

• Sostituisci a mano ogni “ ” con ".
• Copia le configurazioni direttamente da questa documentazione: qui le virgolette sono già corrette.
• Verifica con cat -v config.json o jq . config.json: entrambi segnalano il byte errato.

# 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

Matrice dei sintomi

Comandi diagnostici in una riga

Se la matrice dei sintomi non copre il tuo caso, raccogli questi tre elementi:

# 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 rivolgersi a noi

Invia i tre output qui sopra + i primi 8 caratteri della tua chiave + un timestamp UTC a @Oneproviderhelpbot . Ci basta per trovare la tua richiesta nei nostri log in pochi minuti. In Assistenza trovi cosa non ci serve (e non chiediamo mai).