设计一个 小游戏平台的错误码规范，需要做到：

1. 统一规范：所有服务、接口、SDK 使用同一套错误码标准。
2. 可扩展性：支持多模块、多语言（前端、后端、SDK）。
3. 可诊断性：既能给用户友好的提示，又能给开发者提供精确的调试信息。
4. 多层次信息：错误码（Code）、错误信息（Message）、调试上下文（Detail/Trace ID）。

小游戏平台错误码规范（详细版）

1. 错误码结构设计

采用 五位数字码 + 模块前缀 的形式：

[A][BB][CCC]

A   → 错误级别（1=系统级，2=业务级，3=第三方依赖）
BB  → 模块编码（两位）
CCC → 具体错误编号（三位）

示例

• 10001 → 系统错误（未知错误）
• 201001 → 用户模块（01）登录失败
• 202002 → 游戏模块（02）上传文件过大
• 203003 → 支付模块（03）回调签名验证失败

2. 模块划分（BB）

3. 错误级别（A）

4. 错误码设计示例

系统级错误（1xxxx）

用户模块（2-01-xxx）

游戏模块（2-02-xxx）

支付模块（2-03-xxx）

广告模块（2-04-xxx）

开发者模块（2-05-xxx）

风控安全模块（2-07-xxx）

第三方依赖错误（3xxxx）

5. 错误响应格式（API 统一规范）

1
2
3
4
5
6
7

{
  "code": 201002,
  "message": "Token 无效或已过期",
  "detail": "jwt signature invalid",
  "trace_id": "abc123xyz",
  "timestamp": "2025-09-27T10:20:30Z"
}

• code → 错误码（唯一标识）
• message → 面向用户的友好提示
• detail → 面向开发者的调试信息（可选）
• trace_id → 便于日志追踪和问题定位
• timestamp → 出错时间

6. 设计原则

1. 前后端统一：前端展示 message，后台日志记录 detail。
2. 可国际化：message 支持 i18n（中/英/日）。
3. 幂等设计：支付、广告上报等接口必须返回一致的错误码，避免重复处理。
4. 安全性：对外屏蔽敏感调试信息（如 SQL 错误、栈信息）。
5. 文档化：所有错误码需在 API 文档/Swagger 中列出。

📌 一句话总结： 小游戏平台的错误码规范需要 模块化、统一化、可追踪，既能保证用户友好提示，又能帮助开发者快速定位问题，同时考虑国际化和合规性。

• PRD
• Minigame
• API
• CODE