# 8.2 错误码对照表

:::tip 概述
业务错误码定义在 `utility/apperr`，经 `internal/consts` 别名转出（internal 层只依赖 consts 一个入口）。对外信封除 401 外统一显示为 1，本表用于理解 msg 背后的原因分类。
:::

## 通用码

| 码 | 常量 | 消息 |
|---|---|---|
| 1 | CodeFailed | 操作失败 |
| 400 | CodeParamError | 参数校验失败 |
| 401 | CodeUnauthorized | 登录已过期，请重新登录 |
| 403 | CodeForbidden | 没有该操作权限 |
| 429 | CodeTooManyRequests | 请求过于频繁，请稍后再试 |
| 500 | CodeServerError | 服务器内部错误 |
| 1009 | CodeRecordExists | 记录已存在 |
| 1010 | CodeRecordNotFound | 记录不存在 |

## 认证与账户

| 码 | 常量 | 消息 |
|---|---|---|
| 1001 | CodeUserNotFound | 用户不存在 |
| 1002 | CodeUserDisabled | 账号已被禁用 |
| 1003 | CodePasswordWrong | 密码错误 |
| 1004 | CodeCaptchaError | 验证码错误或已过期 |
| 1008 | CodeTokenInvalid | Token无效或已失效 |
| 1012 | CodeOldPwdWrong | 原密码错误 |

## 租户

| 码 | 常量 | 消息 |
|---|---|---|
| 1005 | CodeTenantExpired | 租户已过期 |
| 1006 | CodeTenantDisabled | 租户已禁用 |
| 1007 | CodeTenantUserLimit | 租户用户数已达上限 |
| 1013 | CodeTenantNotFound | 租户不存在 |

## 业务约束（删除守卫等）

| 码 | 常量 | 消息 | 场景 |
|---|---|---|---|
| 1011 | CodeHasChildren | 存在下级或关联记录，不能删除 | 树形删除守卫 |
| 1014 | CodeInUse | 记录已被引用，不能删除 | 引用删除守卫 |
| 1015 | CodeDemoMode | 演示环境，禁止操作! | demo 中间件命中 |

## 角色常量（非错误码）

| 常量 | 值 | 说明 |
|---|---|---|
| RoleCodeSuperAdmin | ROLE_SUPER_ADMIN | 超管角色编码（保留） |
| PermWildcard | 通配权限码 | 超管通配（保留） |

保留编码仅平台初始化数据可用，租户自建角色禁止采用（防同名提权；超管判定另有 IsPlatform 门控双重防线）。

## 新增错误码规约

1. 定义在 `utility/apperr`（码值 + 中文默认消息）
2. 在 `internal/consts/biz_err.go` 别名转出
3. 编号段规划：1xxx 认证租户业务类 / 10xx 守卫类
4. 业务侧经 `consts.CodeXxx` 哨兵或 `apperr.Newf(consts.CodeXxx.Code(), "fmt", a...)` 上抛

## 对外语义提醒

前端能稳定分支的只有 0 / 1 / 401 三值；细分码用于**服务端日志、排障与文档**。前端如需细分处理，以 msg 关键字或后续扩展专用字段为准，不建议直接依赖内部码。

## 下一步

→ [8.3 分页查询规范](/zh/api-spec/pagination.html)