修复 401、403、429 和 5xx 错误

快速解决 OneProvider API 的问题：400、401、403、404、429、503 和 504 的现象、原因与办法，以及 Claude Code 登录、VPN 和何时联系客服。

十二种每周都会遇到的具体故障。症状 → 原因 → 一行修复。

全部模型、功能与价格面向 AI 智能体的文档索引： https://oneprovider.dev/docs/llms.txt 开始之前运行 curl -s https://api.oneprovider.dev/v1/models -H "x-api-key: $ANTHROPIC_API_KEY"。如果返回了非空的 JSON 模型列表，说明您的网络连通和身份验证都没有问题，您遇到的情况只与具体请求有关，而不是基础设施的问题。

热门问题

需要登录 Claude Code 吗？401 和“Auth conflict”怎么办

不需要。OneProvider 密钥无需 Claude 账号即可使用。对于 Claude Code，请设置 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN（密钥会以 Authorization: Bearer 发送）。该变量的优先级高于已保存的登录状态和其他变量，也不会弹出确认提示。我们的网关同样接受 ANTHROPIC_API_KEY（x-api-key 请求头），但在交互模式下，Claude Code 会让您对这类密钥确认一次，而被拒绝的密钥会被静默忽略（可在 /config → Use custom API key 中重新启用）。

如果您看到登录界面、401 Invalid API key 或 Auth conflict，请逐步排查：

运行 /status：它应显示 OneProvider 的 Anthropic base URL，以及一行写明您所用变量的 Auth token 或 API key。如果 Login method 一行显示的是 claude.ai 账号，说明该变量没有传入当前会话。
Auth conflict（同时存在 claude.ai 登录和密钥）：运行 /logout；您的变量会保留。
401 Invalid API key：别的 ANTHROPIC_AUTH_TOKEN（来自其他服务的令牌）覆盖了您的密钥，或值里混入了多余的引号或空格。请把它设置为完整的 OneProvider 密钥，不带引号。
变量已写在项目的 .claude/settings.json 里，但登录界面仍然出现：该配置块是在首次运行设置之后才读取的，所以请把变量放在 shell 中或 ~/.claude/settings.json 里。

bash

# 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

使用 Codex CLI 需要登录 ChatGPT 吗？

不需要。只要 ~/.codex/config.toml 中的 oneprovider provider 已生效（env_key = "ONEPROVIDER_API_KEY"），Codex 只凭密钥就能工作。如果出现 ChatGPT 登录提示或 "You've hit your usage limit"，说明 provider 没有生效，请求发到了 ChatGPT。

请按以下顺序检查：model_provider 和 model 两行位于文件最顶部，在任何 [table] 之前；Codex 已完全重启，且任务是新建的；密钥已在同一个终端中 export：

bash

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

完整步骤见 Codex (OpenAI) 页面。

需要 VPN 吗？有没有地区限制？

不需要 VPN，OneProvider 没有地区限制。端点 api.oneprovider.dev 全球均可访问，不会按地区屏蔽流量。

更糟的是，VPN / VLESS 代理常常会在两方面破坏 API 连接：

SSE 流式输出在代理内部被缓冲，导致输出在中途被截断。
HTTP/2 + ALPN 协商在中继节点处失败，客户端会看到 connection reset。

如果您遇到流被截断、connection reset 或随机超时，请关闭 VPN / VLESS 代理后重试。我们这边不会缓冲流式输出。

配置中的 JSON 解析错误（或 429）

最常见的原因是 JSON 配置中混入了“智能”引号（“ ”）。从即时通讯软件、Notion、Google Docs，或会把 ASCII 引号自动替换成排版引号的浏览器中复制内容时就会出现。JSON 解析器只接受普通的 ASCII "。

有时配置损坏不会表现为“JSON parse error”，而是 429：客户端把没有收到的回答当成了速率限制。处理方法相同：

手动把每一个 “ ” 都替换为 "。
直接从本文档复制配置：这里的引号已经是正确的。
用 cat -v config.json 或 jq . config.json 校验，两者都会标出有问题的字节。

bash

# 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

症状对照表

参考数据

症状	可能的原因	解决办法
每个请求都返回 401 authentication_error	密钥未设置、格式有误，或复制粘贴时混入了多余的换行 / 引号。	`echo "${ANTHROPIC_API_KEY:?missing}" \| wc -c # expect 68 (sk- + 64 hex + newline)`
429 “Insufficient balance on this API key”	该密钥已没有余额。重试没有用：响应中带有 x-should-retry: false。	`curl -sH "Authorization: Bearer $ANTHROPIC_API_KEY" https://api.oneprovider.dev/v1/dashboard/balance # then top up your cabinet (bot or app.oneprovider.dev)`
403 permission_error “API key expired”	密钥已过有效期。	`请在个人中心的“密钥”页面延长该密钥，或签发新密钥。`
404 “The requested API endpoint does not exist”	base URL 不对：缺少 /v1，或重复了 /v1（/v1/v1）。	`OpenAI 客户端：https://api.oneprovider.dev/v1。Claude Code 和 Anthropic SDK：https://api.oneprovider.dev（不带 /v1）。`
请求高峰时出现 429 rate_limit_error	短时间内请求过多。	`遵守 Retry-After，并以逐渐延长的间隔重试。减少并行请求。`
400 “Model X is not available on this API key”	您密钥的方案不包含此模型，或模型名称已过时。	`请从 GET /v1/models 或 /docs/api/models 页面的表格中选择模型。`
503 “Temporary provider issue on our side, retry in a minute”	我们这边出现了临时故障。您的密钥和请求都没有问题。	`以逐渐延长的间隔重试：1 秒、2 秒、4 秒，最长到一分钟。`
非流式调用返回 504 “Service timed out; retry later”	较长的生成任务（大上下文加工具）超过 6 分钟仍未开始返回，或运行超过了 10 分钟。	`传入 stream:true：流式请求会立即开始返回。如果一个回答需要超过 10 分钟，请拆分任务。`
工具调用被文字取代（“I would have called X...”）	客户端发送了 tool_choice:{any\|tool} → API 将其改写为 auto 加提示；模型没有听从提示。	`收紧用户提示词（“Use the X tool to do Y”），或换用更强的模型。`
OPENAI_API_KEY 覆盖了我的 OneProvider 密钥	shell 配置文件（~/.zshrc、~/.bashrc）里有旧的 export，盖住了新值。	`在当前 shell 中执行 unset OPENAI_API_KEY，然后用 grep -nE 'OPENAI_API_KEY' ~/.zshrc 找到并清理。`
Codex 要求用 ChatGPT 登录，或提示“You've hit your usage limit”	oneprovider 这个 provider 没有生效：请求发到了 ChatGPT，而不是我们这里。	`把 model_provider = "oneprovider" 放在 ~/.codex/config.toml 的最顶部（任何 [table] 之前），密钥放在 ONEPROVIDER_API_KEY 中，并新建一个本地任务。详见 /docs/clients/codex。`
Cursor / Claude Code：流式响应在输出中途被截断	几乎都是客户端的网络代理或 VPN 缓冲了 SSE 数据块。	`关闭代理 / VPN 后重试。我们会在数据块就绪后立即发送，不做缓冲。`

一行诊断命令

如果症状对照表没有覆盖您的情况，请收集以下三项信息：

bash

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

何时联系我们

请把上面三项输出、密钥的前 8 个字符以及一个 UTC 时间戳发给 @Oneproviderhelpbot 。这足以让我们在几分钟内从日志中找到您的请求。我们不需要（也绝不会索取）哪些信息，请见获取支持。

最后更新: 2026-11-08 发现问题？ @Oneproviderhelpbot