8.2 错误码对照表
概述
业务错误码定义在 internal/consts/biz_err.go（gcode.Register 语义值）。注意 Fail 映射规则：除 401 外全部降级为 code=1 返回前端——细分码主要用于日志与语义区分。
基础错误码
| 码 | 常量 | 含义 | 触发场景 |
|---|---|---|---|
| 1 | CodeFailed | 通用操作失败 | 未归类错误的默认出口 |
| 400 | CodeParamError | 参数校验失败 | gvalid 标签校验不过（文案取 # 后缀） |
| 401 | CodeUnauthorized | 登录已过期，请重新登录 | 令牌缺失/过期/黑名单（唯一保留原码返回） |
| 403 | CodeForbidden | 没有该操作权限 | HasPerm 权限判定不过 |
| 429 | CodeTooManyRequests | 请求过于频繁 | RateLimit 超限 |
| 500 | CodeServerError | 服务器内部错误 | panic 兜底 / 未预期错误 |
业务错误码（1000+）
| 码 | 含义 | 触发模块/场景 |
|---|---|---|
| 1001 | 用户不存在 | auth.Login findUser 未命中 |
| 1002 | 账号禁用 | auth.Login status!=1 |
| 1003 | 密码错误 | auth.Login bcrypt 比对失败 |
| 1004 | 验证码错误 | captcha.Verify 失败/过期 |
| 1005 | 租户已过期 | Tenant 中间件 / mustLoadTenant expire_time 已过 |
| 1006 | 租户已禁用 | Tenant 中间件 / mustLoadTenant status!=1 |
| 1007 | 租户用户数上限 | user.Add checkTenantUserMax 超 max_user_num |
| 1008 | Token 无效 | oauth2 Refresh：typ 非 refresh / 已在黑名单（防重放） |
| 1009 | 记录已存在 | 唯一预检（UniqueFields/CheckUnique）命中 |
| 1010 | 记录不存在 | 详情/更新/删除目标缺失 |
| 1011 | 存在下级或关联 | 删除守卫（dept 子级 / menu 子菜单等） |
| 1012 | 原密码错误 | index.UpdatePassword 旧密码校验失败 |
| 1013 | 租户不存在 | 租户定位失败 |
| 1014 | 记录已被引用 | 删除守卫（role 被用户引用等） |
| 1015 | 演示环境禁止操作 | Demo 中间件拦截写操作（app.demo=true） |
使用规约
text
后端上抛：gerror.NewCodef(consts.CodeUserNotExist, "用户不存在")
→ Bind 包装层 response.Fail → 除 401 外降级 code=1（msg 保留）
前端识别：
code=0 成功
code=1 失败（弹 msg——"用户不存在"等细分语义在 msg 里）
code=401 未认证（跳登录）
code=403 无权限（可定制提示）
code=429 限流（可定制"请稍后再试"）为什么细分码降级为 1
前端只需三条分流规则（0/1/401）即可覆盖全部场景；细分码留在服务端日志与 msg 中，避免前端维护 20+ 分支。需要按细分码做 UI 差异化时，读 msg 或扩展信封（不建议破坏现有约定）。
排障对照
| 用户看到 | 码 | 深层原因排查 |
|---|---|---|
| "登录已过期" | 401 | 令牌过期/被拉黑（登出/轮换/强退） |
| "没有该操作权限" | 403 | gmeta permission ↔ 菜单节点 ↔ 角色勾选 ↔ 身份缓存 |
| "请求过于频繁" | 429 | 限流阈值（认证入口 10/分钟更严） |
| "演示环境，禁止操作!" | 1→1015 msg | app.demo=true |
| 其他业务提示 | 1 | msg 即细分语义；服务端日志有细分码 |