Fix 401, 403, 429 and 5xx Errors

Twelve concrete failure modes we see week-in, week-out. Symptom → cause → one-line fix.

Top questions

Do I need to log into Claude Code? What about 401 and “Auth conflict”

No. The OneProvider key works without a Claude account. For Claude Code set ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN (the key is sent as Authorization: Bearer). This variable takes precedence over a saved login and over the other variables, and needs no approval prompt. Our gateway also accepts ANTHROPIC_API_KEY (x-api-key header), but in interactive mode Claude Code asks you once to approve such a key and silently ignores a declined one (re-enable it under /config → Use custom API key).

If you see the login screen, 401 Invalid API key or Auth conflict, go step by step:

1. Run /status: it should show the OneProvider Anthropic base URL and an Auth token or API key line naming your variable. A Login method line with a claude.ai account means the variable did not reach the session.
2. Auth conflict (both a claude.ai login and a key): run /logout; your variables stay.
3. 401 Invalid API key: a foreign ANTHROPIC_AUTH_TOKEN (a token from another service) overrides your key, or the value has a stray quote or space. Set it to the full OneProvider key, without quotes.
4. The login screen stays although the variables are in a project’s .claude/settings.json: that block is read after first-run setup, so put the variables in your shell or 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

Do I need to log into ChatGPT for Codex CLI?

No. Codex CLI reads OPENAI_BASE_URL and OPENAI_API_KEYfrom the environment. When both point to OneProvider, Codex bypasses the ChatGPT sign-in entirely and talks to our endpoint. So you can skip the auth screen.

If a stale token or shell-rc export gets in the way:

unset OPENAI_API_KEY
rm -f ~/.codex/auth.lock
# then re-export the values from your redeem page and restart codex
export OPENAI_BASE_URL="https://api.oneprovider.dev/v1"
export OPENAI_API_KEY="sk-..."
codex

Full walkthrough on the Codex (OpenAI) page.

Do I need a VPN? Any regional restrictions?

No VPN is needed — OneProvider has no regional restrictions. The endpoint api.oneprovider.dev is reachable worldwide and does not geoblock traffic.

Worse, VPN / VLESS proxies often break the API connection in two ways:

• SSE streaming is buffered inside the proxy — the stream gets cut off mid-token.
• HTTP/2 + ALPN negotiation breaks at relay hops — the client sees connection reset.

If you’re seeing cut-off streams, connection reset, or random timeouts, disable the VPN / VLESS proxy and retry. We do not buffer streams on our side.

JSON parse error in config (or a 429)

The most common cause is “smart” quotes (“ ”) in your JSON config. They appear when you copy from a messenger, Notion, Google Docs, or a browser that auto-replaces ASCII quotes with typographic ones. JSON parsers only accept plain ASCII ".

Sometimes a broken config doesn’t surface as “JSON parse error” but as a 429: the client treats the missing answer as a rate limit. Same fix:

• Replace every “ ” with " by hand.
• Copy configs directly from this documentation — the quotes are already correct here.
• Validate with cat -v config.json or jq . config.json — both flag the bad byte.

# 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

Symptom matrix

Diagnostic one-liners

If the symptom matrix didn’t hit your case, capture these three pieces of evidence:

# 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"

When to escalate

Send the three outputs above + the first 8 characters of your key + a UTC timestamp to @Oneproviderhelpbot . That’s enough for us to find your request in our logs within minutes. See Get support for what we don’t need (and never ask for).