中转 API 调用老报错？401 / 429 / 无可用渠道 / over quota 排查指南

一、先分清：错误来自「你」还是「中转」

中转链路是：你 → 中转服务 → 上游官方/渠道。报错可能出在任一环。一个快速判断法：

• 报错信息是标准官方格式（如 invalid_api_key、rate_limit_exceeded）→ 多半是上游/Key 的问题；
• 报错是中文或中转自定义文案（如「无可用渠道」「分组 xxx 下模型 yyy 无可用渠道」）→ 是中转侧的调度/配置问题。

二、401 Unauthorized：中转不认你的 Key

常见原因：

1. Key 填错 / 带空格：重新复制一遍。
2. 请求头用错协议：
   • OpenAI 兼容：Authorization: Bearer sk-xxx
   • Anthropic 原生：x-api-key: xxx + anthropic-version: 2023-06-01
3. Key 过期 / 被中转重置：找中转商确认。

{ "error": { "message": "Invalid token", "code": "invalid_api_key" } }

三、「无可用渠道（distributor）」：中转没给你的模型配渠道

这是中转特有的报错，长这样：

分组 svip 下模型 claude-opus-4-x 无可用渠道（distributor）

含义：你的 Key 所在的「分组」下，没有绑定这个模型的上游渠道。原因通常是：

• 你请求的模型名这个中转根本没有（换个它支持的模型名）；
• 你的分组/套餐不包含该模型（升级套餐或换 Key）；
• 中转把该模型的上游渠道下线了（等它恢复或换渠道）。

排查：先调用中转的 /v1/models 看它到底提供哪些模型；对不上就是模型名的问题。

四、429 / over quota：限流或额度耗尽

429 在中转场景要分三种：

提示	含义	处理
rate_limit / RPM 超限	请求太频繁	降并发 + 指数退避重试
insufficient_quota / 余额不足	账户没钱了	充值 / 换有额度的 Key
over quota	该 Key/分组当日配额用尽	等次日配额恢复，或升级

退避重试参考：

import time, random
def with_retry(fn, n=5):
    for i in range(n):
        try:
            return fn()
        except RateLimited:
            time.sleep((2 ** i) + random.random())  # 1s,2s,4s...+抖动
    raise RuntimeError("多次重试仍失败")

五、额度用完 / 掉线：一批 Key 怎么快速巡检

中转 Key 经常「今天好好的，明天就掉」。写个小巡检脚本定期跑：

import requests

def probe(base, key, model="gpt-4o-mini"):
    try:
        r = requests.post(f"{base}/v1/chat/completions",
            headers={"Authorization": f"Bearer {key}"},
            json={"model": model, "messages":[{"role":"user","content":"ping"}],
                  "max_tokens":5}, timeout=15)
    except Exception as e:
        return f"网络错误 {e}"
    return {200:"OK", 401:"Key失效", 429:"限流/额度",}.get(
        r.status_code, f"HTTP{r.status_code} {r.text[:80]}")

配合 cron 每天跑一遍，Key 掉线第一时间发现。

六、常规错误码速查

状态码	含义	排查方向
400	参数错误	model 名拼错、body 格式、部分模型不吃 temperature
403	无权限	地区限制、模型/分组无权限
404	路径错	/v1/chat/completions vs /v1/messages、model 不存在
5xx	上游故障	稍后重试，用中转时多半是中转节点问题

七、与其逐条猜，不如一键定位

中转报错的麻烦在于：问题可能出在 Key、模型名、协议、额度、上游渠道任何一环，手动一个个排太慢。

推荐一个免费在线工具 CheckToken（Token检测）：https://www.checktoken.cn/

填入接口地址 + API Key + 模型，它会自动发真实请求，把 401/403/429/无可用渠道等报错翻成中文人话，自动探测协议，还能识别中转是否被降级 / 掺水。个别检测项报错也会单独提示、建议重试。排查中转问题时先用它跑一遍，能快速判断是 Key 的问题、模型名的问题，还是中转渠道的问题。

总结

• 401 看 Key 和请求头协议；
• 无可用渠道 看模型名和分组套餐；
• 429 / over quota 看限流和配额；
• 批量 Key 用脚本 + cron 巡检；
• 拿不准就用在线工具一键定位。

中转虽便宜，但报错也多，把这套排查记熟，能少踩很多坑。