「小游戏服务平台」错误码手册

By Leeting Yan

小游戏平台错误码手册 v1.0

1. 总体说明

  • 错误码格式：[A][BB][CCC]

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

  • 统一返回结构：

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

2. 系统级错误（100xx）

Code HTTP Message EN JP 说明
10001 500 系统错误，请稍后再试 System error システムエラー 未知错误
10002 400 请求参数无效 Invalid request parameter 無効なリクエスト 参数校验失败
10003 503 服务不可用 Service unavailable サービス利用不可 微服务宕机或熔断
10004 403 权限不足 Permission denied 権限がありません 用户未授权
10005 429 请求过于频繁 Too many requests リクエストが多すぎます 触发限流保护

3. 用户模块（201xxx）

Code HTTP Message EN JP 说明
201001 401 用户名或密码错误 Incorrect username or password ユーザー名またはパスワードが間違っています 登录校验失败
201002 401 Token 无效或已过期 Token is invalid or expired トークンが無効または期限切れです JWT 校验失败
201003 403 用户未实名 User not verified ユーザー未認証 需要实名认证
201004 403 用户被冻结 Account suspended アカウントが凍結されています 风控冻结

4. 游戏模块（202xxx）

Code HTTP Message EN JP 说明
202001 400 游戏上传失败 Upload failed アップロード失敗 文件损坏/格式错误
202002 400 游戏包大小超过限制 Game package too large ゲームパッケージが大きすぎます >500MB
202003 403 游戏审核未通过 Game review failed ゲーム審査に失敗しました 内容违规
202004 404 游戏已下架 Game removed ゲーム削除済み 被下架或删除

5. 支付模块（203xxx）

Code HTTP Message EN JP 说明
203001 404 支付订单不存在 Order not found 注文が存在しません 无效订单号
203002 402 支付失败 Payment failed 支払いに失敗しました 网关拒绝
203003 400 回调签名验证失败 Signature verification failed 署名検証失敗 安全校验未通过
203004 409 提现处理中 Withdrawal in process 出金処理中 幂等保护

6. 广告模块（204xxx）

Code HTTP Message EN JP 说明
204001 404 广告库存不足 No ad available 広告在庫不足 无可展示广告
204002 400 广告点击无效 Invalid ad click 無効な広告クリック 作弊/重复点击
204003 500 广告结算失败 Ad settlement failed 広告決済失敗 广告竞价异常

7. 开发者模块（205xxx）

Code HTTP Message EN JP 说明
205001 202 报表数据延迟 Report data delayed レポート遅延 数据同步中
205002 400 提现申请超限 Withdrawal limit exceeded 出金上限超過 超过每日限额
205003 400 插件上传失败 Plugin upload failed プラグインアップロード失敗 包格式错误

8. 风控安全模块（207xxx）

Code HTTP Message EN JP 说明
207001 403 账号涉嫌作弊 Cheating detected 不正検出 异常操作
207002 403 IP 黑名单限制 IP blocked IP ブラックリスト制限 拦截访问
207003 429 请求异常高频 Too frequent requests 異常リクエスト頻発 触发限流

9. 第三方依赖错误（301xxx）

Code HTTP Message EN JP 说明
301001 504 支付网关超时 Payment gateway timeout 決済ゲートウェイタイムアウト 微信/支付宝超时
301002 502 CDN 分发失败 CDN delivery failed CDN 配信失敗 节点异常
301003 503 云存储不可用 Cloud storage unavailable クラウドストレージ利用不可 OSS/S3 故障

10. 错误码维护流程

  1. 申请新错误码：开发提交 PR，修改 errors.yaml
  2. CI 校验：自动检测错误码重复/缺失字段
  3. 文档生成：通过脚本生成 ERRORS.md + SDK 错误码映射
  4. 前端/SDK 同步：每次发版前更新映射文件
  5. 监控告警：核心错误码绑定 Prometheus 指标

📌 总结

  • 结构化：统一 errors.yaml 配置
  • 国际化：支持多语言提示（至少中/英/日）
  • 可追踪：携带 trace_id，方便排查
  • 可运维：绑定监控和告警，快速响应
  • 可持续：自动化生成文档和 SDK 映射