错误码

本文汇总了 Hub API 中所有可能返回的错误码。

当 API 返回非 200 的 HTTP Status Code 时，Response Body 中包含统一的 ErrorResponse 结构，其中 error 字段为下表中的错误码。

公共错误码

以下错误码可能在所有 API 中返回：

Error	HTTP Status	Description
invalid_signature	401	签名验证不通过。可能原因：Authorization header 缺失或格式错误、Partner 不存在、签名计算结果不一致。
timestamp_expired	401	请求时间戳过期。Timestamp 与服务端时间偏差超过 15 分钟。
partner_disabled	403	合作方已被禁用。合作方被禁用后，所有 API 调用都将返回此错误。用户已有的绑定关系不受影响，但不能发起新的绑定或奖励发放。
invalid_request	400	请求不合法。包括：参数缺失或格式错误、game_id 未授权给该合作方、指定的活动 / 奖励包不存在等。具体原因请查看 message 字段。
internal_error	500	服务端内部错误。此类错误通常可以重试。

业务错误码

以下错误码仅在特定 API 中返回：

Error	HTTP Status	涉及 API	Description
binding_not_found	400	查询绑定、发放奖励	该用户在该游戏中未绑定角色。
role_not_found	400	查询绑定	绑定的角色不存在（例如角色已被删除）。
event_not_active	400	发放奖励	活动不在有效期内，或活动状态不是「进行中」。
event_in_testing	403	发放奖励	活动处于测试中，非内部测试员不可参与。
reward_not_found	400	查询奖励	指定的奖励发放记录不存在。
claim_limit_exceeded	400	发放奖励	该角色在该奖励包上的领取次数已达上限。
duplicate_grant	400	发放奖励	使用相同 partner_grant_reward_id 的请求已成功发放，本次为重复请求，不会重复发放。
conflict_grant	409	发放奖励	当前有其他发奖请求正在处理中（同一角色与奖励包上的并发请求）。
failed_grant	400	发放奖励	奖励发放失败。该错误不可重试，使用相同的 partner_grant_reward_id 再次调用仍会失败。

错误处理建议

• invalid_signature：请检查签名算法实现是否正确，可使用 签名认证 文档中的完整示例进行验证。
• partner_disabled：请联系世游运营对接人确认合作方状态。
• binding_not_found：用户尚未绑定角色。合作方应引导用户先完成 绑定流程。
• event_not_active：请确认活动的状态和时间窗口。活动可能尚未开始、已结束、或处于非活跃状态。
• event_in_testing：活动处于测试状态，仅内部测试员可参与。请确认活动状态或联系世游运营对接人。
• claim_limit_exceeded：该角色已达到此奖励包的领取上限，不应再次发放。
• duplicate_grant：说明此前已经成功发放过，本次请求不会重复发放。合作方可安全地将此视为成功，如需确认发放详情可调用 查询奖励。
• conflict_grant：同一角色与奖励包上有其他发奖请求正在处理中。此错误可以重试，建议稍后使用相同的 partner_grant_reward_id 重新发起请求。
• failed_grant：奖励发放最终失败且不可重试。使用相同的 partner_grant_reward_id 再次调用仍会返回 failed_grant。
• internal_error：建议使用指数退避策略进行重试。