Zivv Docs

主题

错误码 ​

本页列出 Zivv API 返回的真实错误码与排查方法。遇到报错时，先看响应里的 HTTP 状态码和 error.message，再对照下表定位。

错误响应格式 ​

不同协议格式返回的错误 JSON 结构不同，但都包含 message（错误描述）。

json
{
  "error": {
    "message": "model is required",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}
json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "model is required"
  }
}
json
{
  "error": {
    "code": 400,
    "message": "model is required",
    "status": "INVALID_ARGUMENT"
  }
}

状态码总览 ​

状态码type含义
400invalid_request_error请求格式错误、缺少参数，或该模型当前无可用渠道
401authentication_errorAPI Key 缺失或无效
402insufficient_balance余额不足，或用户/Key 配额已用尽
403permission_error模型被禁用、不在 Key 白名单内，或客户端类型不匹配
404not_found_error端点或模型不存在
405api_errorHTTP 方法不支持（接口只接受 POST）
429rate_limit_error触发限流，或团队预算已用尽
500api_error服务内部错误
502api_error上游响应异常
503api_error服务暂时不可用
529overloaded_error上游过载

错误信息已脱敏

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

常见错误及排查 ​

401 · missing api key / invalid api key ​

原因： 没带 API Key，或 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 · insufficient balance ​

原因： 账户余额低于最低额度（0.01）。

排查： 前往 订阅页面 充值，充值后立即恢复。

402 · quota limit exceeded / key quota limit exceeded ​

原因： 触发了消费上限——前者是用户总额度用尽，后者是这个 API Key 单独设的额度用尽。

排查： 在 令牌管理 查看 Key 的额度设置，或在控制台查看账户配额。额度是累计消费限制，不会自动重置。

403 · model 'xxx' is not allowed for this API key ​

原因： 这个 API Key 设了模型白名单，请求的模型不在其中。

排查： 在 令牌管理 检查该 Key 的「可用模型」设置，把目标模型加进去，或换一个不限模型的 Key。

403 · model 'xxx' is not available ​

原因： 该模型在平台被禁用或已下架。

排查： 在 模型广场 确认模型 ID 拼写正确且仍在售，换用其他可用模型。

403 · this channel requires a specific client... ​

原因： 你用的分组下，渠道限定了客户端类型（按 User-Agent 过滤，例如只允许 Claude Code），当前客户端不匹配。

排查： 换用该分组要求的客户端，或换一个不限客户端的分组。不确定时附上你的客户端名称反馈给管理员。

400 · model is required ​

原因： 请求体里没有 model 字段。

排查： 确认客户端配置了模型 ID，请求体包含 "model": "xxx"。

400 · invalid request body ​

原因： 请求体不是合法 JSON。

排查：

  1. 用 JSON 校验工具检查请求体（多余逗号、引号未闭合等）
  2. Codex 若出现压缩请求解析错误，先检查旧代理链；Zivv 当前已支持压缩，必要时按 Codex 配置指南 临时关闭请求压缩
  3. Anthropic 格式需包含 max_tokens

400 · model 'xxx' is not available, please use a different model ​

原因： 该模型当前没有任何可用渠道（与 403 的「被禁用」不同，这里是路由层找不到能服务的渠道）。

排查： 稍后重试；持续出现则换用其他模型，或反馈给管理员。

429 · rate limit exceeded ​

原因： 请求频率超过 Key 的 RPM/RPH 限制。

处理：

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

def request_with_retry(url, headers, data, max_retries=3):
    for i in range(max_retries):
        resp = requests.post(url, headers=headers, json=data)
        if resp.status_code == 429:
            retry_after = int(resp.headers.get('Retry-After', 5))
            time.sleep(retry_after)
            continue
        return resp
    raise Exception("Max retries exceeded")

429 · quota exhausted, please retry later ​

原因： 目标分组下所有渠道都在限流。

处理： 等待 1-2 分钟后重试，或换用其他分组/模型。

429 · team daily/monthly/total budget exceeded / member budget exceeded ​

原因： 团队预算（日 / 月 / 总）或成员子预算已用尽。

处理： 联系团队管理员调整预算，或等待预算周期重置。

529 · service overloaded, please retry later ​

原因： 上游模型服务过载。

处理： 等待片刻后重试，或换用其他模型。

503 · service temporarily unavailable, please try again later ​

原因： 目标分组下渠道因混合原因（限流 + 过载 + 其他）全部失败。

处理： 等待 1-2 分钟后重试；持续出现请反馈给管理员，并附上反馈格式所需信息。

连接失败 / Connection Refused ​

排查：

  1. 确认 Base URL 用 https://（不是 http://）
  2. 确认 Base URL 是否带 /v1 后缀（见 FAQ）
  3. 检查网络连接
  4. 确认服务在线：curl https://zivv.pro/health

还是解决不了？ ​

按 问题反馈格式 整理信息再反馈，能大幅加快排查。最关键的是：模型 ID、分组、客户端、协议格式、完整报错。

Zivv — OpenAI / Anthropic / Gemini 多协议 AI Gateway

© 2026 Zivv