prd

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

小游戏平台错误码手册 v1.0 1. 总体说明 错误码格式：[A][BB][CCC] A → 错误级别（1=系统级，2=业务级，3=第三方依赖） BB → 模块编码 CCC → 模块内编号 统一返回结构：

Leeting Yan 3 分钟阅读 1194 字

小游戏平台错误码手册 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）

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

3. 用户模块（201xxx）

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

4. 游戏模块（202xxx）

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

5. 支付模块（203xxx）

CodeHTTPMessageENJP说明
203001404支付订单不存在Order not found注文が存在しません无效订单号
203002402支付失败Payment failed支払いに失敗しました网关拒绝
203003400回调签名验证失败Signature verification failed署名検証失敗安全校验未通过
203004409提现处理中Withdrawal in process出金処理中幂等保护

6. 广告模块（204xxx）

CodeHTTPMessageENJP说明
204001404广告库存不足No ad available広告在庫不足无可展示广告
204002400广告点击无效Invalid ad click無効な広告クリック作弊/重复点击
204003500广告结算失败Ad settlement failed広告決済失敗广告竞价异常

7. 开发者模块（205xxx）

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

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

CodeHTTPMessageENJP说明
207001403账号涉嫌作弊Cheating detected不正検出异常操作
207002403IP 黑名单限制IP blockedIP ブラックリスト制限拦截访问
207003429请求异常高频Too frequent requests異常リクエスト頻発触发限流

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

CodeHTTPMessageENJP说明
301001504支付网关超时Payment gateway timeout決済ゲートウェイタイムアウト微信/支付宝超时
301002502CDN 分发失败CDN delivery failedCDN 配信失敗节点异常
301003503云存储不可用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 映射

继续阅读

探索更多技术文章

浏览归档，发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页