错误码与限流

HTTP 状态码速查

状态码	含义	常见原因	处理
200	成功	-	-
400	Bad Request	请求 JSON 格式错 / 参数非法	按错误 message 修
401	Unauthorized	Token 无效 / 漏 `sk-` / 用错 header（`Authorization` vs `x-api-key`）	检查 token + header
402	Payment Required	余额不足 / 令牌已用完额度	控制台 → 令牌 / 账号 → 查额度
403	Forbidden	IP 白名单不匹配 / 模型禁用	去令牌页查
404	Not Found	URL 拼错（比如 `/v1/chat/completion` 少个 s）	对照 `03-api-reference.md`
413	Payload Too Large	请求 body 超限（输入 > 某阈值）	缩短输入或分多次
429	Too Many Requests	触发令牌 QPM 上限 / 上游限流	见"限流"节
500	Internal Server Error	我们后端 bug	发 TG + 提供 request-id
502	Bad Gateway	上游返回异常 / 上游超时	自动降级应急，若持续看 TG 告警
503	Service Unavailable	所有备用渠道都挂	我们会 10 分钟内处理，贴在状态面板
504	Gateway Timeout	上游 > 600s 未响应	通常是超长推理，切 `api-direct.226-ai.com:10443`

常见错误信息 & 真实含义

`Model X not found / No available channel for model X`

模型名拼错（多少号位、有无日期、横杠 vs 点号）
该模型所在渠道全部被禁用（比如 OpenAI 渠道还没充值，gpt-* 全返回这个）
解决：curl /v1/models 拉一把当前真正可用的列表

`insufficient_quota` / `账户余额不足`

账号余额或令牌的总额度 ≤ 0
解决：后台充值 / 联系管理员补额度（内测期）

`Prompt is too long`

输入 tokens 超模型上下文上限
Claude 系列：200K tokens（≈ 130K 汉字）
Gemini 3 Flash：1M tokens
解决：截断输入、分章调用、换大上下文模型

`context_length_exceeded`

同上

`Authentication failed (upstream)`

我们的上游 key 挂了（如订阅账号被 Anthropic 封 / 商业中转 key 过期）
通常我们会自动切备用渠道，你看到这个是所有备用都挂
解决：贴 request-id 到 TG 群，管理员 10-30 分钟处理

`Claude Code 专用分组` 或 `group kiro (distributor)` 之类

上游中转商的 key 分组限制（某些中转商对"非 Claude Code 客户端"拒答）
你用的客户端被识别为非 Claude Code
解决：换用 Anthropic 原生端点 /v1/messages（Claude Code 就是用这个）或换模型让路由到别的渠道

`Connection reset by peer` / 中途断流

长推理 > 100 秒 Cloudflare 橙云超时
解决：https://api-direct.226-ai.com:10443 直连入口

`Invalid anthropic-version`

发 /v1/messages 时没带 anthropic-version: 2023-06-01 header
解决：加上

限流（Rate Limiting）

触发层

按优先级从内到外：

令牌 QPM —— 你建令牌时设置的每分钟请求上限（默认 60）
账号总 QPM —— 账号级上限（默认 200）
上游渠道限流 —— 我们某条上游被限（比如 Max 订阅 20x 档 = 5h 窗口 900 消息）
Cloudflare —— 大流量攻击才触发

响应头

429 响应会带：

x-ratelimit-limit-requests: 60
x-ratelimit-remaining-requests: 0
x-ratelimit-reset-requests: 30s
retry-after: 30

SDK 自动 backoff

Python OpenAI SDK 和 Anthropic SDK 都内建 429 指数退避。直接别管，SDK 会自己重试。

手写客户端的 retry 建议

python

import time, random

def call_with_retry(fn, max_retries=3):
    for attempt in range(max_retries):
        try:
            return fn()
        except Exception as e:
            if attempt == max_retries - 1: raise
            wait = (2 ** attempt) + random.uniform(0, 1)  # 指数退避 + 抖动
            time.sleep(wait)

怎么提额

令牌 QPM：自己控制台 → 令牌编辑 → 改 QPM 字段
账号总 QPM：联系管理员（要承诺不做爬虫、合规用途）
上游限流触发：系统自动切备用渠道，如果持续 429 是我们配置问题，你贴 request-id 给我们查

我们怎么告警

后台 alert-cron 容器每小时扫一遍，异常信号会 TG 推送给管理员：

某用户 1 小时消耗超阈值
某渠道连续 5xx 比例 > 20%
某上游 key 被上游封（401 / 403 比例暴涨）

你作为用户不会直接收到这些告警，但能感受到"某次请求异常慢 / 失败"的时候管理员已经在处理。

故障自助诊断流程

遇到问题按顺序排查：

1. 能不能 curl 通？

bash

curl https://api.226-ai.com/v1/models -H "Authorization: Bearer sk-xxx"

返回模型列表 → 基础链路通，问题在你的客户端配置
401 → token 错
连接不通 → 网络 or DNS

2. 换客户端试

Postman / Insomnia 手搓一发。能通 → 你 SDK 配置有坑。

3. 换入口试

主入口 vs api-direct.226-ai.com:10443。一个通一个不通 → CF 路径问题。

4. 看 console 日志

console.226-ai.com → 日志。有记录 = 请求已到我们这儿，失败在路由或上游。没记录 = 请求没过来，问题在客户端/网络。

5. 看服务监控

status.226-ai.com 看整体健康状态。红的话全员都受影响，等修即可。

6. 还不行发 TG

贴：

时间（精确到秒）
request-id（响应 header 里）
你的 token 名（不是 token 本身！）
错误信息

管理员看到这 4 项能在 5 分钟内定位问题。

错误码与限流 ​

HTTP 状态码速查 ​

常见错误信息 & 真实含义 ​

Model X not found / No available channel for model X ​

insufficient_quota / 账户余额不足 ​

Prompt is too long ​

context_length_exceeded ​

Authentication failed (upstream) ​

Claude Code 专用分组 或 group kiro (distributor) 之类 ​

Connection reset by peer / 中途断流 ​

Invalid anthropic-version ​

限流（Rate Limiting） ​

触发层 ​

响应头 ​

SDK 自动 backoff ​

手写客户端的 retry 建议 ​

怎么提额 ​

我们怎么告警 ​

故障自助诊断流程 ​

1. 能不能 curl 通？ ​

2. 换客户端试 ​

3. 换入口试 ​

4. 看 console 日志 ​

5. 看服务监控 ​

6. 还不行发 TG ​