错误代码参考
错误码为 5 位数字，格式：XYYZZ
- X：
4= 用户错误（客户端问题），5= 内部错误（服务端问题） - YY：模块编号（
00= 通用，01+ = 各功能模块） - ZZ：模块内序号
通用 (00)
| 错误码 | 说明 |
|---|---|
| 50001 | 服务端内部错误 / 配置解析失败 |
| 50002 | 数据库通用错误 |
| 50003 | 无效时间戳 |
认证与安全
JWT (01)
| 错误码 | 说明 |
|---|---|
| 40101 | 无效的令牌 |
| 40102 | 令牌已过期 |
| 50101 | JWT 编码失败 |
| 50102 | JWT 验证失败 |
GitHub OAuth2 (05)
| 错误码 | 说明 |
|---|---|
| 40501 | GitHub 认证失败（Token 交换返回错误） |
| 40502 | 未获取到 access_token |
| 40503 | 缺少 code 参数 |
| 40504 | 缺少 state 参数 |
| 40505 | state 验证失败 |
| 40506 | 回调函数未注册 |
| 50501 | Token 请求发送失败 |
| 50502 | Token 响应解析失败 |
| 50503 | 获取用户信息请求失败 |
| 50504 | 用户信息解析失败 |
| 50505 | 获取用户邮箱请求失败 |
| 50506 | 用户邮箱解析失败 |
Argon2 (24)
| 错误码 | 说明 |
|---|---|
| 52401 | Argon2 配置错误 |
| 52402 | Argon2 哈希计算失败 |
| 52403 | Argon2 盐值生成失败 |
| 52404 | Argon2 哈希解析失败 |
RBAC (28)
| 错误码 | 说明 |
|---|---|
| 42801 | 角色不存在 |
| 42802 | 不能删除默认角色 |
| 42803 | 权限不足 |
| 52801 | 建表失败 |
| 52802 | 初始化数据失败 |
| 52803 | 权限检查失败 |
| 52804 | 角色分配失败 |
| 52805 | 角色创建失败 |
限流 (20)
| 错误码 | 说明 |
|---|---|
| 42001 | 请求被限流拒绝 |
微信生态
微信小程序登录 (02)
| 错误码 | 说明 |
|---|---|
| 40201 | 微信 API 业务错误 |
| 50201 | 构建请求 URL 失败 |
| 50202 | 发送请求失败 |
| 50203 | 解析响应 JSON 失败 |
| 50204 | 反序列化登录响应失败 |
微信 APP 登录 (03)
| 错误码 | 说明 |
|---|---|
| 40301 | 微信 API 业务错误 |
| 50301 | 构建请求 URL 失败 |
| 50302 | 发送请求失败 |
| 50303 | 解析响应 JSON 失败 |
| 50304 | 反序列化登录响应失败 |
微信网页登录 (21)
| 错误码 | 说明 |
|---|---|
| 42101 | 微信 API 业务错误 |
| 42102 | 缺少 code 参数 |
| 42103 | 缺少 state 参数 |
| 42104 | state 验证失败 |
| 52101 | 构建请求 URL 失败 |
| 52102 | 换取 access_token 请求失败 |
| 52103 | 解析 access_token 响应失败 |
| 52104 | 反序列化 access_token 响应失败 |
| 52105 | 刷新 access_token 请求失败 |
| 52106 | 解析刷新 access_token 响应失败 |
| 52107 | 检验 access_token 请求失败 |
| 52108 | 解析检验 access_token 响应失败 |
| 52109 | 获取用户信息请求失败 |
| 52110 | 解析用户信息响应失败 |
| 52111 | 回调函数未注册 |
微信公众号授权 (22)
| 错误码 | 说明 |
|---|---|
| 42201 | 微信 API 业务错误 |
| 42202 | 缺少 code 参数 |
| 52201 | 构建请求 URL 失败 |
| 52202 | 换取 access_token 请求失败 |
| 52203 | 解析 access_token 响应失败 |
| 52204 | 反序列化 access_token 响应失败 |
| 52205 | 刷新 access_token 请求失败 |
| 52206 | 解析刷新 access_token 响应失败 |
| 52207 | 检验 access_token 请求失败 |
| 52208 | 解析检验 access_token 响应失败 |
| 52209 | 获取用户信息请求失败 |
| 52210 | 解析用户信息响应失败 |
| 52211 | 回调函数未注册 |
微信公众号管理 (23)
| 错误码 | 说明 |
|---|---|
| 42301 | 微信 API 业务错误 |
| 42302 | access_token 未配置 |
| 52301 | 获取 access_token 请求失败 |
| 52302 | 解析 access_token 响应失败 |
| 52303 | 发送模板消息请求失败 |
| 52304 | 解析模板消息响应失败 |
| 52305 | 创建菜单请求失败 |
| 52306 | 解析菜单响应失败 |
| 52307 | 删除菜单请求失败 |
| 52308 | 素材操作请求失败 |
| 52309 | 解析素材响应失败 |
| 52310 | 获取菜单请求失败 |
| 52311 | 个性化菜单请求失败 |
微信支付 (09)
| 错误码 | 说明 |
|---|---|
| 40901 | 配置缺少必要字段 |
| 40902 | 预下单 API 业务错误 |
| 40903 | 回调通知验签失败 |
| 50901 | 私钥加载失败 |
| 50902 | 签名生成失败 |
| 50903 | 请求失败 |
| 50904 | 预下单请求失败 |
| 50905 | 预下单响应解析失败 |
| 50906 | 查询订单响应解析失败 |
| 50907 | 退款响应解析失败 |
| 50908 | 账单响应解析失败 |
微信虚拟支付 (06)
| 错误码 | 说明 |
|---|---|
| 40601 | 微信 API 登录业务错误 |
| 40602 | 微信登录 session 已过期 |
| 50601 | 构建请求 URL 失败 |
| 50602 | 发送登录请求失败 |
| 50603 | 解析登录响应 JSON 失败 |
| 50604 | 反序列化登录响应失败 |
微信内容安全 (07)
| 错误码 | 说明 |
|---|---|
| 40701 | 微信 API 业务错误 |
| 40702 | 内容为空或超过 2500 字 |
| 50701 | 构建请求 URL 失败 |
| 50702 | 发送请求失败 |
| 50703 | 解析响应 JSON 失败 |
| 50704 | 反序列化响应失败 |
| 50705 | 获取 access_token 失败 |
| 50706 | 解析 access_token 响应失败 |
微信内容安全回调 (08)
| 错误码 | 说明 |
|---|---|
| 40801 | 缺少验签参数 |
| 40802 | 签名验证失败 |
| 40803 | 消息体解密失败 |
阿里云
阿里云 OSS (04)
| 错误码 | 说明 |
|---|---|
| 40401 | STS 未配置 role_arn |
| 50401 | HMAC-SHA256 初始化失败 |
| 50402 | HMAC-SHA1 初始化失败 |
| 50403 | 签名计算失败 |
| 50404 | STS 请求发送失败 |
| 50405 | STS 响应错误 |
| 50406 | STS 响应解析失败 |
支付宝 (26)
| 错误码 | 说明 |
|---|---|
| 42601 | 回调通知验签失败 |
| 42602 | 回调通知参数缺失 |
| 52601 | 私钥加载失败 |
| 52602 | 公钥加载失败 |
| 52603 | 签名失败 |
| 52604 | 验签失败 |
| 52605 | 请求发送失败 |
| 52606 | 响应解析失败 |
阿里云短信 (11)
| 错误码 | 说明 |
|---|---|
| 41101 | 短信凭证未配置 |
| 51101 | HMAC-SHA1 初始化失败 |
| 51102 | 短信 API 请求失败 |
| 51103 | 短信回执回调未注册 |
腾讯云
腾讯云 COS (12)
| 错误码 | 说明 |
|---|---|
| 51201 | HMAC-SHA256 初始化失败 |
| 51202 | 签名计算失败 |
| 51203 | 请求发送失败 |
| 51204 | 响应解析失败 |
腾讯云短信 (17)
| 错误码 | 说明 |
|---|---|
| 41701 | 短信凭证未配置 |
| 51701 | HMAC-SHA256 初始化失败 |
| 51702 | 短信 API 请求失败 |
| 51703 | 短信回执回调未注册 |
腾讯地图 (14)
| 错误码 | 说明 |
|---|---|
| 41401 | 腾讯地图 Key 未配置 |
| 51401 | 腾讯地图 API 请求失败 |
| 51402 | 腾讯地图响应解析失败 |
| 51403 | 腾讯地图 API 返回错误 |
地图
高德地图 (13)
| 错误码 | 说明 |
|---|---|
| 41301 | 高德 Key 未配置 |
| 51301 | 高德 API 请求失败 |
| 51302 | 高德响应解析失败 |
| 51303 | 高德 API 返回错误 |
存储与数据
数据库 (25)
| 错误码 | 说明 |
|---|---|
| 52501 | 数据库连接失败 |
| 52502 | 数据库配置错误 |
Redis / Valkey (16)
| 错误码 | 说明 |
|---|---|
| 51601 | Redis 连接失败 |
| 51602 | Redis 连接丢失 |
| 51603 | Redis 命令执行失败 |
MemKV (29)
| 错误码 | 说明 |
|---|---|
| 42901 | Key 不存在 |
| 42902 | 索引越界 |
| 42903 | 值不是数字 |
| 52901 | 命令执行失败 |
文件处理
本地文件 (19)
| 错误码 | 说明 |
|---|---|
| 41901 | 文件不存在 |
| 41902 | 文件过大 |
| 41903 | 文件类型不允许 |
| 41904 | 路径不合法 |
| 41905 | 路径遍历攻击 |
| 51901 | 文件读取失败 |
| 51902 | 文件写入失败 |
| 51903 | 文件删除失败 |
| 51904 | 目录创建失败 |
| 51905 | 目录读取失败 |
Excel (18)
| 错误码 | 说明 |
|---|---|
| 51801 | 打开 Excel 文件失败 |
| 51802 | 工作表不存在或读取失败 |
| 51803 | 写入 Excel 失败 |
消息通知
邮件 (10)
| 错误码 | 说明 |
|---|---|
| 41001 | 邮箱账户未找到 |
| 41002 | 邮箱账户 ID 重复 |
| 41003 | 默认邮箱 ID 不存在 |
| 51001 | SMTP 连接失败 |
| 51002 | 邮件发送失败 |
推送 (27)
| 错误码 | 说明 |
|---|---|
| 42701 | 推送请求被拒绝 |
| 52701 | 推送请求发送失败 |
| 52702 | 推送响应解析失败 |
工具
ACME (31)
| 错误码 | 说明 |
|---|---|
| 53101 | ACME 操作失败（通用） |
| 53102 | 创建缓存目录失败 |
| 53103 | 发现 ACME 目录失败 |
| 53104 | 创建账户失败 |
| 53105 | 创建证书订单失败 |
| 53106 | 获取授权失败 |
| 53107 | 该授权不支持 HTTP-01 验证 |
| 53108 | 验证通知失败 |
| 53109 | 域名验证超时 |
| 53110 | 订单无效 / 域名验证失败 |
| 53111 | 生成密钥对失败 |
| 53112 | 生成 CSR 失败 |
| 53113 | 完成订单失败 |
| 53114 | 证书签发超时 |
| 53115 | 获取证书失败 |
| 53116 | 写入证书/私钥失败 |
| 53117 | 读取证书文件失败 |
| 53118 | 解析证书失败 |
链路追踪 (30)
| 错误码 | 说明 |
|---|---|
| 43001 | Span 数据格式错误 |
| 43002 | Trace 不存在 |
| 53001 | SQLite 初始化失败 |
| 53002 | SQLite 操作失败 |
| 53003 | 未配置存储后端 |
| 53004 | HTTP 存储初始化失败 |
| 53005 | HTTP 请求失败 |
| 53006 | TCP 存储初始化失败 |
定时任务 (35)
| 错误码 | 说明 |
|---|---|
| 53501 | Cron 表达式解析失败 |