# Brisk 错误码文档（内部实施版）

**版本**：v0.1  
**日期**：2026-04-08  
**说明**：当前工程内已使用的错误码分组与含义。

---

## 1. 返回结构

```json
{
  "code": 0,
  "message": "ok",
  "data": {}
}
```

- `code = 0` 表示成功
- 非 `0` 表示失败

---

## 2. 错误码分组

| 范围 | 模块 |
|---|---|
| `10001 - 10099` | 客户端 token / bootstrap / auth |
| `20001 - 20099` | 后台鉴权 |
| `21000 - 21999` | 后台项目 |
| `22000 - 22999` | 后台动态配置 |
| `23000 - 23999` | 后台玩家 |
| `24000 - 24999` | 后台审计日志 |
| `30000 - 30999` | 动态配置读取 |
| `40000 - 40999` | 公告 |
| `41000 - 41999` | 后台公告 |
| `50000 - 50999` | 排行榜 |
| `51000 - 51999` | 后台榜单 |
| `60000 - 60999` | 存档 |
| `70000 - 70999` | 玩家空间 |
| `80000 - 80999` | 限流 |

---

## 3. 当前已使用错误码

| 错误码 | 接口/模块 | 含义 |
|---|---|---|
| `10001` | 客户端鉴权 | 缺少 token |
| `10002` | 客户端鉴权 | token 无效 |
| `10010` | `bootstrap` | 缺少必填查询参数 |
| `10011` | `bootstrap` | 项目不存在 |
| `10020` | `auth/login/exchange` | 请求体格式错误 |
| `10021` | `auth/login/exchange` | 缺少必填字段 |
| `10022` | `auth/login/exchange` | 登录交换失败 |
| `10023` | `auth/logout` | 缺少会话 |
| `10024` | `auth/logout` | 退出登录失败 |
| `10025` | `auth/login/exchange` | 项目维护中 |
| `10026` | `auth/login/exchange` | 玩家已封禁 |
| `10003` | 客户端访问控制 | 项目维护中 |
| `10004` | 客户端访问控制 | 玩家已封禁 |
| `10005` | 客户端访问控制 | 访问校验失败 |

| 错误码 | 接口/模块 | 含义 |
|---|---|---|
| `20001` | 后台鉴权 | 缺少后台 token |
| `20002` | 后台鉴权 | 后台 token 无效 |
| `20010` | `admin/auth/login` | 请求体格式错误 |
| `20011` | `admin/auth/login` | 缺少用户名或密码 |
| `20012` | `admin/auth/login` | 后台登录失败 |

| 错误码 | 接口/模块 | 含义 |
|---|---|---|
| `21010` | `admin/projects` | 项目列表查询失败 |
| `21011` | `admin/projects` | 创建项目请求体错误 |
| `21012` | `admin/projects` | 缺少项目名称或 game_key |
| `21013` | `admin/projects` | 创建项目失败 |
| `21014` | `admin/projects/{id}` | 项目 ID 非法 |
| `21015` | `admin/projects/{id}` | 更新请求体错误 |
| `21016` | `admin/projects/{id}` | 项目不存在 |
| `21017` | `admin/projects/{id}` | 更新项目失败 |

| 错误码 | 接口/模块 | 含义 |
|---|---|---|
| `22010` | `admin/configs` | project_id 非法 |
| `22011` | `admin/configs` | 配置列表查询失败 |
| `22012` | `admin/configs` | 创建配置请求体错误 |
| `22013` | `admin/configs` | project_id 非法 |
| `22014` | `admin/configs` | 创建配置失败 |

| 错误码 | 接口/模块 | 含义 |
|---|---|---|
| `23010` | `admin/players` | project_id 非法 |
| `23011` | `admin/players` | 玩家列表查询失败 |
| `23012` | `admin/players/{player_id}/ban` | player_id 非法 |
| `23013` | `admin/players/{player_id}/ban` | 玩家不存在 |
| `23014` | `admin/players/{player_id}/ban` | 封禁失败 |
| `23015` | `admin/players/{player_id}/unban` | player_id 非法 |
| `23016` | `admin/players/{player_id}/unban` | 玩家不存在 |
| `23017` | `admin/players/{player_id}/unban` | 解封失败 |

| 错误码 | 接口/模块 | 含义 |
|---|---|---|
| `24010` | `admin/audit-logs` | 审计日志查询失败 |

| 错误码 | 接口/模块 | 含义 |
|---|---|---|
| `30010` | `config/current` | 缺少必填查询参数 |
| `30011` | `config/current` | 项目不存在 |
| `30012` | `config/current` | 配置读取失败 |

| 错误码 | 接口/模块 | 含义 |
|---|---|---|
| `40010` | `announcements` | 缺少会话 |
| `40011` | `announcements` | 公告查询失败 |
| `40012` | `announcements/{id}/read` | 缺少会话 |
| `40013` | `announcements/{id}/read` | 公告 ID 非法 |
| `40014` | `announcements/{id}/read` | 公告不存在 |
| `40015` | `announcements/{id}/read` | 标记已读失败 |

| 错误码 | 接口/模块 | 含义 |
|---|---|---|
| `41010` | `admin/announcements` | project_id 非法 |
| `41011` | `admin/announcements` | 公告列表查询失败 |
| `41012` | `admin/announcements` | 创建公告请求体错误 |
| `41013` | `admin/announcements` | 缺少公告必填字段 |
| `41014` | `admin/announcements` | 创建公告失败 |

| 错误码 | 接口/模块 | 含义 |
|---|---|---|
| `50010` | `ranks/top` | 缺少会话 |
| `50011` | `ranks/top` | 榜单查询失败 |
| `50012` | `ranks/me` | 缺少会话 |
| `50013` | `ranks/me` | 玩家排名查询失败 |
| `50014` | `ranks/around-me` | 缺少会话 |
| `50015` | `ranks/around-me` | 附近排名查询失败 |
| `50016` | `ranks/score` | 缺少会话 |
| `50017` | `ranks/score` | 分数请求体错误 |
| `50018` | `ranks/score` | 分数提交失败 |

| 错误码 | 接口/模块 | 含义 |
|---|---|---|
| `51010` | `admin/ranks` | project_id 非法 |
| `51011` | `admin/ranks` | 榜单列表查询失败 |
| `51012` | `admin/ranks` | 创建榜单请求体错误 |
| `51013` | `admin/ranks` | 缺少榜单必填字段 |
| `51014` | `admin/ranks` | 创建榜单失败 |

| 错误码 | 接口/模块 | 含义 |
|---|---|---|
| `60010` | `archives/meta` | 缺少会话 |
| `60011` | `archives/meta` | 存档元数据查询失败 |
| `60012` | `archives/upload` | 缺少会话 |
| `60013` | `archives/upload` | 上传表单错误 |
| `60014` | `archives/upload` | 缺少文件 |
| `60015` | `archives/upload` | 文件读取失败 |
| `60016` | `archives/upload` | 版本冲突 |
| `60017` | `archives/upload` | 校验值不匹配 |
| `60018` | `archives/upload` | 存档超出大小限制 |
| `60019` | `archives/upload` | 上传失败 |
| `60020` | `archives/download` | 缺少会话 |
| `60021` | `archives/download` | 存档不存在 |
| `60022` | `archives/download` | 下载失败 |

| 错误码 | 接口/模块 | 含义 |
|---|---|---|
| `70010` | `spaces/{player_id}` | 缺少会话 |
| `70011` | `spaces/{player_id}` | 玩家不存在 |
| `70012` | `spaces/{player_id}` | 空间读取失败 |
| `70013` | `spaces/me` | 缺少会话 |
| `70014` | `spaces/me` | 请求体错误 |
| `70015` | `spaces/me` | 空间更新失败 |
| `70016` | `spaces/{player_id}/like` | 缺少会话 |
| `70017` | `spaces/{player_id}/like` | 玩家不存在 |
| `70018` | `spaces/{player_id}/like` | 点赞失败 |
| `70019` | `spaces/{player_id}/like` | 缺少会话 |
| `70020` | `spaces/{player_id}/like` | 玩家不存在 |
| `70021` | `spaces/{player_id}/like` | 取消点赞失败 |
| `70022` | `spaces/me/visits` | 缺少会话 |
| `70023` | `spaces/me/visits` | 访客列表查询失败 |

| 错误码 | 接口/模块 | 含义 |
|---|---|---|
| `80001` | 限流中间件 | 请求过于频繁 |
| `80002` | 限流中间件 | 限流服务不可用 |

---

## 4. 使用规则

- 新接口优先复用所属模块的错误码段
- 成功统一返回 `code = 0`
- 同一类错误尽量复用已有错误码
- 新增错误码时同步更新本文件