Skip to content

Error Handling

Jump to bottom
Sliverkiss edited this page Sep 14, 2026 · 1 revision

错误分类与处理策略

网关把上游（CodeBuddy）的各类响应分类为可机读的错误类型（internal/upstream），再由账号池与 HTTP 层按类型套用不同策略。分类逐次按优先级判定：

402 类（积分耗尽标记） →  session 死亡(12153) →  账号故障(11140/14017)
  →  软限流标记 →  HTTP 429 →  HTTP 404 →  HTTP 5xx →  内容拦截 / 参数错误 →  兜底

错误类型与标记

错误类型 判定来源 关键标记 / 特征
ErrHardCredit 402 类 + 2xx 正文积分文案 英文积分耗尽短语；中文「积分不足 / 额度不足 / 余额不足」等
ErrSessionDead 会话失效 Offline user session not found；12153
ErrAccountFault 账号级故障 request illegal（11140）；trial not activated（14017）
ErrSoftRate 软限流 rate limit / too many / usage limit；中文「请求过于频繁 / 限流」；6004
ErrNotFound HTTP 404 —
ErrServer HTTP 5xx —
ErrContentBlocked 内容拦截 blocked by security policy / unapproved channel / illegal api invocation
ErrBadParams 参数错误 —
ErrClient 客户端请求问题 —
ErrNone 正常 —

HTTP 状态 → 处理策略

场景 处理 冷却 / 后果
402 + 积分耗尽标记 账号硬冷却到次日 04:00 等签到（09/21 点）恢复；冷却期不参与选号，也不进入全冷却兜底（调了必 402）
429（ErrSoftRate） 软冷却 600s 起 连续触发指数退避：600s × 2^(streak-1)，封顶 soft_rate_max（默认 2h）；成功或签到解冻时 streak 清零
429 + 6004 带「将在 … 重置」时间 模型级独立冷却 冷却截止 = 上游给定 reset_at，不做指数放大；多个模型同时 6004 各自独立计时互不覆盖；该账号对其他模型仍可选（模型豁免）
6004 无时间文案 回落账号级软冷却 同普通 429 退避
404 固定 60s 浅冷却 成本极低，避免雪崩
5xx 记错误、累计熔断失败 不立即冷却；连续失败达到阈值进入熔断（见下）
12153 session dead 连续 3 次才禁用（计数式） 一次偶发 12153（网络抖动 / 刷新竞态）不杀号；refresh 成功 / chat 成功即清计数；连续 3 次 → disabled_reason=12153 session dead
11140 request illegal hard 禁用 disabled_reason= account banned by upstream (11140 request illegal), re-login required；需重登 + 手工复活
14017 trial not activated 账号级短冷却 轮换到其他账号
内容拦截（ErrContentBlocked） 不计惩罚 返回 400 content_blocked + 客户端可读信息，不冷却账号
参数错误（ErrBadParams） 不冷却但轮换 切换账号重试

11140 与 14017 都归入 ErrAccountFault，由响应体是否含 request illegal 区分：前者硬禁用，后者短冷却轮换。

熔断器（Circuit Breaker）

独立于冷却的「病态反复失败」惩罚：

  • 阈值 breaker_threshold（默认 3）：任意错误（含冷却入口）喂入统一失败计数器 fails；
  • 达到阈值触发熔断：breaker_cooldown（默认 30m）起步，按 × 2^retryCount 指数退避，封顶 breaker_cooldown_max（默认 6h）；
  • 与软冷却退避双轨独立：软退避管「短时段被限流」，熔断管「反复失败」；成功 / 统一复活时计数清零。

全冷却兜底

无任何 healthy 账号时，从冷却 / 熔断账号中选「最早到期」的一个重试：

  • disabled 账号永不参与兜底；
  • 硬冷却（CoolHard，余额耗尽）账号排除——调了必 402，浪费轮换；
  • 软冷却 / 熔断账号允许参与（可能已恢复，失败成本仅一轮换）；
  • 兜底命中会打一条 WARN fallback_earliest_expiry 日志。

内容拦截降级

  • prompt.mode=custom（默认）：网关自有提示词替换客户端 system/developer，从源头规避 system 来源的内容误报；
  • prompt.mode=passthrough：原样透传，遇 ErrContentBlocked 时自动切换为内置中性提示词（degradeGate 机制）重试一次；降级门生效到次日北京时间 00:00 后重置；
  • 中平提示词仅保留通用的「帮助、直接、简洁」指令，最大限度降低误报面。

指纹脱敏

features.sanitize_blacklist_fingerprints: true（默认开）时，出站请求体对已知客户端指纹字段做黑名单清洗：

  • 预扫描已知指纹段（如 x-anthropic-billing-header、cc_entrypoint=、"You are Claude Code"、"Main branch ("、github.com/anthropics/、11128 等）；
  • 命中则改写：长尾数字段断笔（如 11128 → 11-128）、模板句逐词替换；
  • 与提示词体系两层叠加，降低上游指纹识别；WB2A_DUMP_REQ=1 可观察改写后的出站请求。

运维可观测

  • 每请求一行表格日志（TTFB / token 速率 / uid，uid 脱敏取前 8 位）；
  • /status 逐账号暴露：cooling / cool_kind（hard_credit / soft_rate）/ cool_remaining_sec / reason / soft_streak / disabled_reason / rate_limited_models（限额台账，见 API-Reference）；
  • 熔断状态为运行态（重启清零），硬禁用 / 冷却 / 软退避计数持久化到 state.json。

Clone this wiki locally