错误码

Agent Token 认证错误

错误信息	原因	解决方案
Authorization header is required	缺少 Authorization Header	添加 Authorization: Bearer {token}
Authorization header format must be Bearer {token}	Header 格式不正确	确认格式为 Bearer<空格>{token}
Invalid token format	Token 不是三段式	确认 Token 格式为 key.timestamp.signature
Invalid token: missing required parts	Token 某部分为空	检查各部分是否都有值
Invalid token: invalid timestamp	时间戳不是合法数字	确认 timestamp 为 Unix 秒级时间戳
Token expired	时间戳超出 ±2 分钟窗口	检查服务器时间，使用当前时间戳重新生成
Invalid agent credentials	API Key 无效或未找到	确认 agent_api_key 正确
Invalid token signature	签名不匹配	确认 agent_api_secret 正确，检查签名算法

通用错误码

错误码	Message	说明
0	success	成功
1001	err.param.invalid	参数缺失或格式错误
1002	err.signature.invalid	签名验证失败
1003	err.request.timeout	请求超时
1004	err.request.duplicate	重复请求（幂等性拦截）

玩家相关

错误码	Message	说明
2001	err.player.not_found	玩家不存在
2002	err.player.duplicate	玩家已存在（注册重复）
2003	err.player.disabled	玩家已被禁用
2004	err.player.password_invalid	密码错误
2005	err.player.register_failed	玩家注册失败
2006	err.player.member_id_invalid	member_id 格式错误

资金相关

错误码	Message	说明
3001	err.fund.insufficient_balance	余额不足
3002	err.fund.invalid_amount	转账金额无效（为 0 或超出限制）
3003	err.fund.duplicate_transfer	转账流水号重复
3004	err.fund.transfer_pending	转账处理中，请稍后查询
3005	err.fund.currency_not_supported	不支持的货币代码

游戏相关

错误码	Message	说明
4001	err.game.not_found	游戏不存在或已下线
4002	err.game.maintenance	游戏维护中
4003	err.game.type_unsupported	不支持的游戏类型
4004	err.game.platform_unsupported	不支持的平台类型
4005	err.game.launch_failed	游戏启动失败
4006	err.game.access_denied	游戏访问权限不足（代理未开通该游戏）

游戏商相关

错误码	Message	说明
5001	err.provider.unavailable	游戏商不可用
5002	err.provider.call_failed	游戏商接口调用失败
5003	err.provider.abnormal_response	游戏商返回异常
5004	err.provider.unsupported	不支持的游戏商
5005	err.provider.feature_unsupported	该游戏商不支持此功能

调试辅助说明（友善排错提示）

当接口返回错误时，msg 字段可能会携带以下具体的中文/英文错误细节，用以帮助运营或开发人员精确定位配置错误：

错误信息 (msg 详细返回)	可能的原因	解决方案 (如何修复)
agent has no access authorization for game_id xxx	平台中未授权该代理进入该游戏。	检查该代理的后台“游戏授权”配置是否包含了该游戏。
agent brand route/mapping not configured for brand xxx	该代理在当前游戏商品牌的商户后台路由未配。	检查商户后台中关于该厂商的“商户映射（Route）”是否建立。
currency XXX is not enabled/supported in brand YYY configurations	商户后台中该厂商未启用/支持该币种。	前往管理员后台，在对应游戏厂商的品牌设置中勾选启用该币种（例如 IDR）。
agent game commission rate not configured for currency XXX and game type YYY	该商户对应的代理未配置该币种和该游戏分类的佣金比例。	前往代理管理后台的“商户佣金配置”，为对应的币种和游戏类型（如 SLOT）添加抽成比例。
Call agent balance callback failed...	本地核心系统去向包网发起“查分回调”时连接失败。	1. 检查商户设置中配置的回调域名（Base URL）是否正确。 2. 检查包网方自己的回调服务器是否在线、IP 白名单是否放行。
Player auto registration failed during game launch	首次启动游戏触发静默注册玩家失败。	数据库连接问题或核心系统校验失败，需联系技术人员排查日志。