错误处理
接口错误契约
平台管理接口遵循统一错误契约(提审等脚本化调用同样适用):
- 错误类别即 HTTP 状态码,400 参数错误、401 未认证、403 无权限、404 资源不存在、409 冲突、429 限流、5xx 服务端错误。
- 每个响应带
X-Error-Code头,成功为 0,失败为 6 位业务错误码。 - 失败时另带
X-Error-Message头,为 URL 编码的中文文案,响应体为空。 - 判断逻辑一律以错误码为准,禁止解析文案文本。
6 位错误码结构为 SSS DD Q:前 3 位为 HTTP 状态,第 4 位为业务域,0 通用、1 账号、2 玩家、3 开发商与游戏内容、4 资金、5 对局与工单,末 2 位为域内序号。
开发商高频错误码
| 错误码 | 文案 | 处理建议 |
|---|---|---|
401002 | 访问令牌已过期 | 用刷新令牌换新后重放 |
401005 | 对局连接凭证无效或已过期 | WebSocket 票据单次有效 30 秒,重连时重新索取票据 |
403104 / 403301 | 开发商账号已停用 | 联系平台 |
429001 | 登录尝试过于频繁 | 每 IP 每分钟 30 次登录,失败 10 次锁 10 分钟,稍后再试 |
400307 | 上架前必须先上传前端包 | 先完成前端包上传 |
400308 | 上架前必须先通过至少一个版本的审核 | 先提审 |
400328 | 上传文件校验失败 | 对照包规范自查 |
400331 | 首次提审需同时上传前端包和后端包 | 补齐两侧 |
400332 | 本次提交未包含新的包内容 | 至少更新一侧再提交 |
400309 | 已归档游戏不能切换版本 | 先恢复上架 |
400312 | 只能使用已过审的版本 | 仅可切换 approved 包 |
400511 | 余额不足 | 游戏内提示余额不足并引导充值 |
500501 | 游戏脚本执行超时 | 优化逻辑耗时,单次回调上限 2 秒 |