帮助中心

遇到接入或使用问题，先在这里自助排查；解决不了再按下方格式反馈，能大幅加快处理。

• 一、常见问题排查
  • 连不上 / 配置后无反应
  • 401 · 提示未认证
  • 402 / 403 · 余额、配额、权限
  • 429 · 触发限流
  • 400 · 请求格式错误
  • 5xx · 服务端错误
• 二、问题如何反馈
  • 反馈模板
  • 字段说明
  • 完整示例
  • 怎么提交

一、常见问题排查

报错时先看响应里的 HTTP 状态码 和 error.message，对照下表定位。需要完整错误码清单见 错误码参考。

连不上 / 配置后无反应

1. Base URL 必须用 https://（不是 http://）

2. 确认 Base URL 是否带 /v1 后缀 —— 不同协议不一样：

   格式	Base URL
   OpenAI（Codex、OpenAI SDK、兼容客户端）	https://zivv.pro/v1
   Anthropic（Claude Code、Anthropic SDK）	https://zivv.pro
   Gemini（Gemini CLI）	https://zivv.pro/v1beta

3. 确认服务在线：curl https://zivv.pro/health

401 · 提示未认证

报错含 missing api key 或 invalid api key：

1. API Key 以 sk- 开头，前后无空格或换行
2. 请求头格式对：
   • OpenAI：Authorization: Bearer sk-xxx
   • Anthropic：x-api-key: sk-xxx
   • Gemini：x-goog-api-key: sk-xxx
3. 在 令牌管理 确认 Key 没过期、没被禁用

402 / 403 · 余额、配额、权限

报错	原因	怎么办
insufficient balance	余额不足	去 订阅页面 充值，充完即恢复
quota limit exceeded	用户总额度用尽	控制台查看配额，或联系管理员
key quota limit exceeded	这个 Key 单独设的额度用尽	在 令牌管理 查看该 Key 额度
model 'xxx' is not allowed for this API key	模型不在 Key 白名单	在 令牌管理 把模型加进「可用模型」，或换个不限模型的 Key
model 'xxx' is not available	模型被禁用或下架	在 模型广场 确认模型 ID 和可用性
this channel requires a specific client	分组的渠道限定客户端（按 UA 过滤）	换该分组要求的客户端，或换不限客户端的分组

429 · 触发限流

报错 rate limit exceeded 或 quota exhausted：

1. 看响应头 Retry-After，等指定秒数后重试
2. 降低请求频率和并发
3. 代码里加指数退避重试

400 · 请求格式错误

• model is required：请求体没带 model 字段，确认客户端配了模型 ID
• invalid request body：请求体不是合法 JSON
• Codex 出现压缩请求解析错误：Zivv 当前已支持压缩，先检查是否经过旧代理；必要时按 Codex 配置指南 临时关闭请求压缩

5xx · 服务端错误

503 / 529 / 502 多是上游模型暂时不可用或过载：等 1-2 分钟重试，或换用其他模型。持续出现请按下方格式反馈。

错误信息已脱敏

上游模型报错时，Zivv 会统一包装成通用文案（如 service unavailable, please retry later），不透传上游原文。所以 message 是 Zivv 的标准提示。

二、问题如何反馈

自查后仍未解决，按下面的模板整理信息，能省去反复追问。

最关键的五项

模型 ID、分组、客户端、协议格式、完整报错 —— 同样的报错在不同组合下原因可能完全不同，这五项缺一不可。

反馈模板

复制填写：

模型 ID：
环境：
客户端：
分组：
故障：
应该怎样：
如何复现：
备注：

字段说明

字段	填什么
模型 ID	从模型广场复制的完整 ID，不要简写
环境	操作系统，如 Windows / macOS / Linux
客户端	客户端名称及版本，如 Claude Code / Cursor
分组	API Key 所属分组，如 Claude MAX
故障	具体现象，附完整报错（含 HTTP 状态码和 error.message）
应该怎样	你预期的正确表现
如何复现	触发问题的最小步骤
备注	对比信息——什么情况正常、什么情况异常

完整示例

模型 ID：YOUR_MODEL_ID
环境：Windows
客户端：Claude Code 2.x
分组：Claude MAX
故障：让它改代码时只回复文字、不实际调用工具编辑文件，使用 Anthropic Messages 格式请求
应该怎样：能正常调用工具（tool use）编辑文件
如何复现：在 Claude MAX 分组下用 Claude Code 让它修改某个文件，模型只输出代码块、不执行编辑
备注：换其他分组正常，纯问答（不涉及改文件）正常

备注里的对比信息最值钱

上面例子里「换其他分组正常、纯问答正常」一句，直接把问题缩小到 Claude MAX 分组 + 工具调用 这一组合，比单说「不会改代码」有用得多。反馈前多想一句：换个分组/模型/客户端还会不会？纯问答（不调用工具）会不会？

怎么提交

整理好信息后发给平台管理员或在反馈渠道提交，附上完整报错原文（截图或文本均可），不要只说「不行」「报错了」。