API 错误处理

错误码

稳定的原因标识符，不会因说明文字调整而变化。

说明

简短且安全的说明，不包含内部代码、数据库查询、机密信息或多余细节。

请求 ID

用于在日志中定位操作并联系支持的唯一标识符。

附加数据

允许的状态、限额、当前状态或安全的拒绝原因。

可重试

明确标示临时错误，同时不取消操作的防重复保护。

重试前延迟

建议的等待秒数或用于请求频率限制和临时不可用场景的 HTTP 头。

字段错误

问题字段列表，包括原因码、值路径及安全说明。

文档引用

说明错误原因及修复方式的固定链接或章节标识符。

格式无效、缺少必填字段、不支持的值、金额精度错误或请求结构无效。

缺少、过期或无效的令牌、API 密钥、签名、请求时间戳或 nonce。

客户端已识别，但缺少执行该操作所需的角色、品牌、市场或权限。

玩家、支付、回合、KYC 检查、提供商或其他对象不存在，或当前客户端无权访问。

对象版本或状态已变更，或者操作标识符已使用但参数不同。

余额不足、超出限额、玩家被阻止、市场被禁止或状态转换无效。

客户端、方法、角色或关键操作允许的请求数量已超限。

外部服务不可用、响应缓慢或暂时不接受操作。

平台发生意外错误，不泄露内部细节，但会提供诊断标识符。

缺少字段、类型无效、不支持的值、金额精度问题以及多个错误同时出现。

无效密钥、过期令牌、签名错误、未授权角色、被阻止的 IP 以及重复使用的 nonce。

请求发送前、操作已被接受后，以及接收最终响应过程中发生连接故障。

HTTP 429、建议等待时间、并发请求以及限制解除后的恢复。

服务不可用、维护、响应无效、通知延迟及状态冲突。

限制尝试次数、逐步增加延迟、暂时停止请求、受控恢复及人工升级。