QM-ServerV2 知识库

Appearance

OAuth 错误码矩阵（HTTP 视角 · 40101001 ~ 40101012） ​

📍 来源：OAuth 文档 errors.html 与 🔵 API Docs → 错误码矩阵（40101xxx） 互补：本文按 HTTP 视角，彼文按业务码视角。

1. 业务错误统一包络 ​

业务错误统一 HTTP 200 + code: 40101xxx。协议层错误（4xx/5xx）走 HTTP 状态码。

完整枚举定义真源：server/src/modules/oauth/oauth.errors.ts（12 工厂，由本文档与该真源双向收敛）。

2. 错误码全量矩阵（按 code 升序） ​

codemsg（默认）HTTP触发场景前端处置
40101001token 无效401access/refresh 解析失败、签名不匹配、refresh 被轮换作废（重放）区分场景：业务请求 401 → 走 rotate 单飞；rotate 自身 401 → 立即登出，禁止重试
40101002token 已过期401access 超过 2h同上，走 rotate
40101003图形验证码错误400captchaCode 不匹配提示错误 + 重新拉 captcha（旧码已消费）
40101004图形验证码已过期400>120s 未使用静默刷新 captcha，不打扰用户
40101005短信发送过于频繁429限流三层任一触发（msg 区分：IP / 60s 间隔 / 日上限）按 msg 文案提示；按钮倒计时遵循 限流规则
40101006短信发送失败502短信通道故障 / SMS 未配置提示稍后再试；需重新拉 captcha
40101007微信绑定失败400code 无效、解绑后无剩余登录方式提示重试；解绑场景检查前置条件
40101008需先同意用户协议与隐私政策412agreementAccepted !== true前端预防：未勾选协议时禁用登录按钮，不该让此错误发生
40101009手机号格式不正确400非 11 位大陆手机号输入框即时校验，理论不该发生
40101010微信接口调用失败502微信侧故障 / 凭据未配置提示「微信登录暂不可用」，留手机号登录兜底
40101011授权范围（scope）不合法400logout scope 非 device/all前端枚举约束，理论不该发生
40101012OAuth 服务内部错误500服务端异常提示「系统繁忙」，可安全重试

3. 处置策略三分法（前端统一封装建议） ​

typescript
type UiAction = 'silent-refresh-captcha' | 'rotate-then-retry' | 'force-logout' | 'toast' | 'bug';

function toUiAction(code: number): UiAction {
  if (code === 40101003 || code === 40101006) return 'silent-refresh-captcha';
  if (code === 40101001 || code === 40101002) return 'rotate-then-retry'; // rotate 自身失败→force-logout
  if (code === 40101004) return 'silent-refresh-captcha';
  if (code >= 40101005 && code <= 40101012) return 'toast';               // 提示类
  return 'bug'; // 未知码：上报埋点，勿死循环
}
UiAction适用错误码前端动作
silent-refresh-captcha40101003 / 40101004 / 40101006静默调用 captcha action 刷新图形码，不打断用户
rotate-then-retry40101001 / 40101002业务请求 401 → 走 rotate 单飞；rotate 自身 401 → 立即登出
toast40101005 / 40101007 / 40101008 / 40101009 / 40101010 / 40101011 / 40101012uni.showToast(msg)
bug未知码上报埋点，勿死循环重试

4. 协议层错误（非 40101xxx） ​

HTTP场景处置
400（path: message 格式）Zod 校验失败（字段缺失/超长/格式错）开发期修复，按 msg 定位字段
404action 不存在 / 路径错误检查统一入口 URL 与 action 拼写
429触发全局限流退避重试
5xx网关/服务异常退避重试 + 上报

5. ⚠️ 与 error-codes.md 的差异 ​

维度本文件（errors.html 视角）error-codes.md（API Docs 视角）
HTTP 状态码401 / 400 / 429 / 502 / 412 / 500统一 200（业务码视角）
错误码范围40101001 ~ 40101012（12 个）40101001 ~ 40101012 + 通用 400/403/500
面向读者前端工程师（联调时排查 HTTP 错）后端 + 全栈（理解业务码体系）
404/5xx 协议层包含不包含（仅业务码）

Why 两份：OAuth 文档站（v2 生产版）按 HTTP 状态码视角组织；项目自己的 error-codes.md 按业务码视角组织。两者互补而非冲突。

6. 错误码一致性原则 ​

  • 错误码 string 值必须稳定（"40101003" 不是数字 40101003）
  • HTTP 状态码根据 §2 矩阵确定（业务错误 200 vs 协议错误 4xx/5xx）
  • msg 文案前端可直接显示，无需翻译
  • 任何错误码变动需同步更新本文 + error-codes.md + 🟢 Internal Wiki → 错误码体系