8.2 错误码对照表

:::tip 概述业务错误码定义在 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）

使用规约

后端上抛：gerror.NewCodef(consts.CodeUserNotExist, "用户不存在")
  → Bind 包装层 response.Fail → 除 401 外降级 code=1（msg 保留）

前端识别：
  code=0  成功
  code=1  失败（弹 msg——"用户不存在"等细分语义在 msg 里）
  code=401 未认证（跳登录）
  code=403 无权限（可定制提示）
  code=429 限流（可定制"请稍后再试"）

::: tip 为什么细分码降级为 1 前端只需三条分流规则（0/1/401）即可覆盖全部场景；细分码留在服务端日志与 msg 中，避免前端维护 20+ 分支。需要按细分码做 UI 差异化时，读 msg 或扩展信封（不建议破坏现有约定）。 :::

排障对照

用户看到	码	深层原因排查
"登录已过期"	401	令牌过期/被拉黑（登出/轮换/强退）
"没有该操作权限"	403	gmeta permission ↔ 菜单节点 ↔ 角色勾选 ↔ 身份缓存
"请求过于频繁"	429	限流阈值（认证入口 10/分钟更严）
"演示环境，禁止操作!"	1→1015 msg	app.demo=true
其他业务提示	1	msg 即细分语义；服务端日志有细分码

3.2 KiB Raw Permalink Blame History Unescape Escape

8.2 错误码对照表

基础错误码

业务错误码（1000+）

使用规约

排障对照

3.2 KiB

Raw Permalink Blame History