常见错误与排查

错误速查表

状态码	常见现象	解决方向
401	Unauthorized / Invalid API Key	API Key 缺失、错误或已禁用
402	Insufficient Balance / Payment Required	余额不足（仅付费模型）
403	Forbidden / No permission	密钥无该模型权限
404	Not Found / Unknown model	Base URL 或模型名称错误
429	Rate limit exceeded / Too many requests	请求频率或并发超限
5xx	Internal Server Error / Bad Gateway	上游服务异常，稍后重试

---

逐一排查

401 — API Key 无效

现象： 401 Unauthorized 或 Invalid API Key

检查清单：

1. ✅ 请求头是否正确携带 Key
   • Claude 协议：x-api-key: sk-xxx
   • OpenAI 协议：Authorization: Bearer sk-xxx
2. ✅ 进入 API 密钥页面，确认密钥未被禁用或删除
3. ✅ Key 是否复制完整（没有截断、没有多余空格）
4. ✅ Key 是否以 sk- 开头

解决： 在密钥页面重新创建新 Key，替换所有配置。

---

402 — 余额不足

现象： 调用付费模型时返回 402 Payment Required

原因： 账户余额不足以支付本次请求的费用

处理：

1. 前往 https://fast.drivecode.top/redeem 兑换余额
2. 或切换到免费模型，免费模型不消耗余额

---

403 — 权限不足

现象： 请求某个模型返回 403 Forbidden

检查：

1. 查询 /v1/models 确认该模型在你的密钥分组内
2. 检查余额是否充足（余额不足也可能返回 403）

解决： 切换到有权限的模型，或在密钥页面更换分组后重新创建 Key。

---

404 — 地址或模型错误

现象： 404 Not Found 或 model not found

检查清单：

1. ✅ Base URL 是否正确（详见 API 地址说明）
2. ✅ 是否重复添加了 /v1（如 https://fast.drivecode.top/v1/v1/...）
3. ✅ 模型名称是否完全匹配（大小写、版本号）

解决： 先用 /v1/models 接口确认正确的模型名称，再复制到请求中。

curl.exe https://fast.drivecode.top/v1/models `
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx"

---

429 — 请求频率超限

现象： 429 Too Many Requests

原因：

• 短时间内发送了大量请求
• 多个程序同时使用同一 API Key

解决： 降低请求频率，在代码中添加请求间隔（建议每次请求间隔 ≥ 200ms），或联系客服提升并发额度。

---

5xx — 上游服务异常

现象： 500 / 502 / 503

处理步骤：

1. 等待 1～5 分钟后重试
2. 尝试切换到其他可用模型
3. 若持续超过 30 分钟，联系客服

---

客户端常见问题

Claude Code 能启动但不能回复

# 1. 确认环境变量已设置
Write-Host $env:ANTHROPIC_API_KEY
Write-Host $env:ANTHROPIC_BASE_URL

# 2. 用 curl 直接测试接口
$body = @{
    model = "<MODEL_ID>"
    max_tokens = 64
    messages = @(
        @{ role = "user"; content = "hi" }
    )
} | ConvertTo-Json -Depth 10 -Compress

curl.exe https://fast.drivecode.top/v1/messages `
  -H "x-api-key: $env:ANTHROPIC_API_KEY" `
  -H "anthropic-version: 2023-06-01" `
  -H "Content-Type: application/json" `
  -d $body

此处 max_tokens = 64 是为了用较少输出完成连通性测试。anthropic-version: 2023-06-01 是 API schema 版本，不是当前年份。

如果 curl 正常但 Claude Code 无法工作：

• 检查 ANTHROPIC_BASE_URL 是否没有加 /v1
• 检查 Claude Code 是否最新版本

Cherry Studio 测试失败

1. 确认选择的服务商类型与 Base URL 匹配（OpenAI vs Claude）
2. API Key 是否完整复制
3. Base URL 末尾是否多了斜杠

Cursor 不响应

1. Cursor 设置 → Models → OpenAI Compatible
2. Base URL 填 https://fast.drivecode.top/v1
3. 填写 API Key
4. 选择模型（从 /v1/models 获取可用模型 ID）
5. 完全重启 Cursor（只刷新窗口不够）

---

其他常见问题

余额用完了怎么办？

余额用完后，付费模型（Claude、GPT 等）将暂时不可用。前往 https://shop.drivecode.top 购买兑换码充值即可继续使用。

PowerShell 命令粘贴后引号报错

Windows PowerShell 的引号规则与 Bash 不同。推荐用变量方式：

$body = @{
    model = "<MODEL_ID>"
    max_completion_tokens = 100
    messages = @(
        @{ role = "user"; content = "hello" }
    )
} | ConvertTo-Json -Depth 10 -Compress

curl.exe https://fast.drivecode.top/v1/chat/completions `
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" `
  -H "Content-Type: application/json" `
  -d $body

支持哪些客户端？

Drivecode API 同时提供 Anthropic 兼容协议和 OpenAI 兼容协议。客户端必须选择与自身接口匹配的协议：

• 🖥️ Claude Code / Codex CLI / Cursor
• 💬 Cherry Studio / ChatBox / LobeChat / NextChat
• 🌐 Open WebUI / 沉浸式翻译
• 📦 Python / Node.js SDK

其中 Codex CLI 必须使用 /v1/responses；支持 Chat Completions 不等于支持 Codex。

详细配置教程请查看对应客户端页面。

---

还是无法解决？

如果以上排查未能解决你的问题，请联系客服并提供以下信息：

• 订单号（如涉及购买）
• 完整的错误信息（截图或错误码）
• 账户邮箱（用于核实身份）

以下信息绝对不要发给任何人

• 完整的 API Key（如需排查，提供前几位即可）
• 账户登录密码
• 兑换码