设计一个 小游戏平台的错误码规范，需要做到：
- 统一规范：所有服务、接口、SDK 使用同一套错误码标准。
- 可扩展性：支持多模块、多语言（前端、后端、SDK）。
- 可诊断性：既能给用户友好的提示，又能给开发者提供精确的调试信息。
- 多层次信息：错误码（Code）、错误信息（Message）、调试上下文（Detail/Trace ID）。
小游戏平台错误码规范（详细版）
1. 错误码结构设计
采用 五位数字码 + 模块前缀 的形式：
[A][BB][CCC]
A → 错误级别（1=系统级，2=业务级，3=第三方依赖）
BB → 模块编码（两位）
CCC → 具体错误编号（三位）
示例
10001 → 系统错误（未知错误）201001 → 用户模块（01）登录失败202002 → 游戏模块（02）上传文件过大203003 → 支付模块（03）回调签名验证失败
2. 模块划分（BB）
| 模块编码 | 模块名称 | 说明 |
|---|
| 01 | 用户模块 | 注册、登录、认证、权限 |
| 02 | 游戏模块 | 上传、审核、分发、运行 |
| 03 | 支付模块 | 订单、支付、提现、回调 |
| 04 | 广告模块 | 广告投放、点击、归因 |
| 05 | 开发者模块 | 报表、收益、工具、插件 |
| 06 | 数据分析 | 埋点、推荐、BI 报表 |
| 07 | 风控安全 | 反作弊、限流、黑名单 |
| 99 | 系统级错误 | 通用错误、服务不可用 |
3. 错误级别（A）
| 级别 | 范围 | 说明 |
|---|
| 1 | 1xxxx | 系统级错误（全局） |
| 2 | 2xxxx | 业务逻辑错误（可预期） |
| 3 | 3xxxx | 第三方依赖错误（支付、云存储等） |
4. 错误码设计示例
系统级错误（1xxxx）
| 错误码 | 错误信息 | HTTP 状态码 | 说明 |
|---|
| 10001 | 系统错误，请稍后再试 | 500 | 未知错误 |
| 10002 | 请求参数无效 | 400 | 参数格式/必填项缺失 |
| 10003 | 服务不可用 | 503 | 微服务宕机或熔断 |
| 10004 | 权限不足 | 403 | 用户未授权 |
| 10005 | 请求过于频繁 | 429 | 限流保护 |
用户模块（2-01-xxx）
| 错误码 | 错误信息 | HTTP 状态码 | 说明 |
|---|
| 201001 | 登录失败，用户名或密码错误 | 401 | 登录校验失败 |
| 201002 | Token 无效或已过期 | 401 | JWT 校验失败 |
| 201003 | 用户未实名 | 403 | 需要实名认证 |
| 201004 | 用户被冻结 | 403 | 风控冻结 |
游戏模块（2-02-xxx）
| 错误码 | 错误信息 | HTTP 状态码 | 说明 |
|---|
| 202001 | 游戏上传失败 | 400 | 文件损坏/不支持格式 |
| 202002 | 游戏包大小超过限制 | 400 | >500MB |
| 202003 | 游戏审核未通过 | 403 | 违规内容 |
| 202004 | 游戏下架 | 404 | 游戏已被删除或下架 |
支付模块（2-03-xxx）
| 错误码 | 错误信息 | HTTP 状态码 | 说明 |
|---|
| 203001 | 支付订单不存在 | 404 | 无效订单号 |
| 203002 | 支付失败 | 402 | 支付网关拒绝 |
| 203003 | 回调签名验证失败 | 400 | 安全校验未通过 |
| 203004 | 提现处理中 | 409 | 幂等性保护 |
广告模块（2-04-xxx）
| 错误码 | 错误信息 | HTTP 状态码 | 说明 |
|---|
| 204001 | 广告库存不足 | 404 | 无可展示广告 |
| 204002 | 广告点击无效 | 400 | 作弊/重复点击 |
| 204003 | 广告结算失败 | 500 | 广告竞价异常 |
开发者模块（2-05-xxx）
| 错误码 | 错误信息 | HTTP 状态码 | 说明 |
|---|
| 205001 | 报表数据延迟 | 202 | 数据同步中 |
| 205002 | 提现申请超限 | 400 | 超过每日限额 |
| 205003 | 插件上传失败 | 400 | 包格式错误 |
风控安全模块（2-07-xxx）
| 错误码 | 错误信息 | HTTP 状态码 | 说明 |
|---|
| 207001 | 账号涉嫌作弊 | 403 | 行为检测异常 |
| 207002 | IP 黑名单限制 | 403 | 拦截访问 |
| 207003 | 请求异常高频 | 429 | 触发限流 |
第三方依赖错误（3xxxx）
| 错误码 | 错误信息 | HTTP 状态码 | 说明 |
|---|
| 301001 | 支付网关超时 | 504 | 微信/支付宝超时 |
| 301002 | CDN 分发失败 | 502 | CDN 节点错误 |
| 301003 | 云存储服务不可用 | 503 | OSS/S3 故障 |
5. 错误响应格式（API 统一规范）
{
"code": 201002,
"message": "Token 无效或已过期",
"detail": "jwt signature invalid",
"trace_id": "abc123xyz",
"timestamp": "2025-09-27T10:20:30Z"
}
code → 错误码（唯一标识）message → 面向用户的友好提示detail → 面向开发者的调试信息（可选）trace_id → 便于日志追踪和问题定位timestamp → 出错时间
6. 设计原则
- 前后端统一：前端展示
message，后台日志记录 detail。 - 可国际化：
message 支持 i18n（中/英/日）。 - 幂等设计：支付、广告上报等接口必须返回一致的错误码，避免重复处理。
- 安全性：对外屏蔽敏感调试信息（如 SQL 错误、栈信息）。
- 文档化：所有错误码需在 API 文档/Swagger 中列出。
📌 一句话总结：
小游戏平台的错误码规范需要 模块化、统一化、可追踪，既能保证用户友好提示，又能帮助开发者快速定位问题，同时考虑国际化和合规性。
7 代码实践：Go 错误码枚举与注册表
本节将错误码规范转化为可直接使用的 Go 枚举 + 注册表 + HTTP 映射，支持自动 trace_id 注入与多语言选择。
3.1 错误码枚举定义
package minigameerr
import (
"sync"
"time"
)
type MiniGameError struct {
Code int
HTTP int
Msg string
Desc string
}
func (e MiniGameError) Error() string { return e.Msg }
func (e MiniGameError) WithTrace(traceID string, lang string) map[string]interface{} {
msg := e.Msg
if lang == "en" { msg = e.Desc }
return map[string]interface{}{
"code": e.Code, "message": msg, "trace_id": traceID,
"timestamp": time.Now().Unix(),
}
}
var registry = sync.Map{}
func Register(code, httpStatus int, msg, desc string) {
registry.Store(code, MiniGameError{Code: code, HTTP: httpStatus, Msg: msg, Desc: desc})
}
func Lookup(code int) (MiniGameError, bool) {
v, ok := registry.Load(code)
if !ok {
return MiniGameError{Code: code, HTTP: 500, Msg: "未知系统错误", Desc: "System error"}, false
}
return v.(MiniGameError), true
}
func init() {
Register(10001, 500, "系统错误，请稍后再试", "Internal server error")
Register(10002, 400, "请求参数无效", "Invalid parameters")
Register(10003, 503, "服务不可用", "Service unavailable")
Register(10004, 403, "权限不足", "Permission denied")
Register(10005, 429, "请求过于频繁", "Rate limit exceeded")
Register(201001, 401, "登录失败", "Login failed")
Register(201002, 401, "Token 无效", "Invalid token")
Register(202002, 400, "游戏包大小超限", "Package size limit exceeded")
}
本章小结
确立了小游戏平台的 5 位数字错误码规范（系统级/业务级/第三方依赖），支持多语言提示与全链路 trace_id 追踪。
延伸阅读
相关专题
📂 本文属于 「小游戏服务平台」完整知识体系。
如果你正在构建一个 SaaS 小游戏平台，可参考 后端架构白皮书 了解多租户、缓存、高可用等通用架构模式。
继续阅读
探索更多技术文章
浏览归档，发现更多关于系统设计、工具链和工程实践的内容。