Appearance
OAuth 错误码矩阵（40101xxx）
⚠️ 所有业务错误 HTTP 状态码都是 200（除非用户被封禁返回 403）。前端必须按
body.code而非 HTTP status 判断业务错误类型。HTTP 400 仅用于 入参校验失败（Pydantic 首 issue），HTTP 403 仅用于 账号被封禁。
错误响应统一格式
json
{
"code": "40101003",
"msg": "短信验证码错误",
"data": null
}错误码全量矩阵
| code | 含义 | 触发 action | 前端 UI 文案 | 后续动作 |
|---|---|---|---|---|
40001001 | 入参校验失败（HTTP 400） | 所有 | <字段路径>: <原因>（如 phone: invalid phone） | 修正表单 |
40101001 | 短信码不存在 / 已过期 / 已被 3 次错作废 | sms-verify, sms-login, bind-phone | 「验证码已失效，请重新获取」 | 引导回 1.2 重发 |
40101003 | 验证码错误（图形码 或 短信码，msg 区分） | sms-send, sms-verify, sms-login, captcha 校验 | 图形码：「图形验证码错误」 短信码：「短信验证码错误」 | 图形码：刷新 captcha 短信码：可继续试（接近 3 次要警告） |
40101004 | 图形验证码已过期（>120s） | sms-send | 「图形验证码已过期」 | 静默刷新 captcha |
40101005 | 限流（三层任一：IP 30/min / 手机号 60s/1 / 手机号 24h/10） | sms-send | msg 区分：「操作过于频繁」/「60s 内已发送」/「已达日上限」 | 按 msg 提示，倒计时保持禁用 |
40101006 | SMS 通道故障 / 凭据未配置期 | sms-send | 「短信通道暂不可用，请稍后再试」 | 重新拉 captcha + 退到登录页 |
40101007 | 微信绑定失败 / unbind 解绑后无登录方式 | callback, unbind | 「绑定失败，请重试」 / 「至少保留一种登录方式」 | callback：重新走 SDK 授权 unbind：UI 提前禁用 |
40101008 | 协议未同意（agreementAccepted 非 literal true） | sms-login, callback | 「请先同意用户协议」 | 提示勾选 |
40101010 | 微信接口失败 / 微信凭据未配置 | callback | 「微信登录暂不可用」 | 手机号登录兜底 |
40101011 | rotate 验签失败 / binding 非 active / 密文缺失 / 用户不存在 | rotate | 「登录已失效」 | 清空本地会话 → 登录页，禁止重试 |
40101012 | rotate 重放（签名合法但与库内不匹配 = 旧 refresh 二次使用） | rotate | 「登录已在其他设备更新」 | ⚠️ 服务端已连坐吊销该设备会话，前端唯一动作：清会话进登录页 |
40301001 | 账号被封禁（HTTP 403） | 所有需鉴权 action | 「账号已被封禁，请联系客服」 | 不允许重试 |
50001001 | 服务异常（HTTP 200） | 所有 | 「服务异常，请稍后重试」 | 退到登录页 |
短信码「错」vs「不存在」必须区分
| code | 语义 | UI 文案 |
|---|---|---|
40101003 | 码错误（可继续试，attempts+1） | 「短信验证码错误，还剩 X 次机会」 |
40101001 | 码不存在 / 过期 / 已被 3 次错作废 | 「验证码已失效，请重新获取」 |
混淆这两个 code 会导致：
- 用户看到「错误」却必须重新发码（体验差）
- 用户看到「不存在」却继续尝试（白白消耗次数）
OATH-M-006 历史教训
背景：早期生产环境 errorHandler 分支顺序错误，导致业务码被吞成 HTTP 状态码（{code:400/401}），前端所有业务码判断失效。
修复：
- 业务异常最先注册 ExceptionHandler
- HTTPException handler 只能兜底
- 业务错误固定 HTTP 200（封禁除外）
前端验证：服务端联调时务必打印原始响应 JSON，确认 code 字段是字符串 40101003 而非 HTTP status。
错误码分配规则
| 区段 | 用途 | 备注 |
|---|---|---|
40001001-40001999 | 入参校验 | Zod / Pydantic 通用 |
40101001-40101099 | OAuth 业务码 | 内部占用，外部对接仅看到字符串值 |
40101100-40101999 | 其他 auth 模块预留 | 密码登录、未来手机号+密码双因子等 |
40301001-40301999 | 账号状态 | 封禁 / 锁定 / 注销 |
50001001-50001999 | 服务异常 | 兜底 |
新增错误码约定：
- 必须先在 🟢 Internal Wiki → 错误码体系 登记
- msg 字段必须能直接展示给用户
- code 区段不可跨模块复用
- 任何 code 变更需要同步更新 Internal Wiki → 错误码体系 + 本文件 + 单测 fixture