通用错误码

错误响应格式见接入说明。程序判断请使用 error.code，不要使用 message。

HTTP	error.code	触发条件	调用方处理
400	INVALID_REQUEST	格式错误、缺少必填字段、字段类型不对、有未声明字段、重复字段、游标无效	修正请求，不要原样重试
401	AUTHENTICATION_FAILED	凭据或签名错误	检查密钥和签名串
401	REQUEST_EXPIRED	X-Timestamp 超出 ±300 秒	校准服务器时间，用新时间戳重新签名
403	MERCHANT_DISABLED	商户已停用新业务	联系平台。已受理的资金仍可查单
403	SCOPE_DENIED	凭据没有该接口权限	联系平台确认开通范围
403	LAUNCH_DENIED	当前不允许该玩家进入游戏	检查玩家和商户状态
404	RESOURCE_NOT_FOUND	资源不存在，或不属于当前商户	检查 ID
404	TRANSACTION_NOT_FOUND	查无此交易	如果原请求可能还在途，稍后用同一 ID 再查
409	INSUFFICIENT_FUNDS	可用余额不足	终态失败，没有扣款
409	FUNDS_UNAVAILABLE	有未确认的资金占用	稍后重试，或先查询未完成的交易
409	IDEMPOTENCY_CONFLICT	同一幂等键或 external_id 对应了不同的请求内容	停止重试，检查业务 ID 是否复用
409	REQUEST_IN_PROGRESS	同一请求还在处理中	稍后查询原资源，不要重新发起
409	CANCELLATION_NOT_ALLOWED	任务已经派发，不能取消	按原任务查询结果
409	INVALID_TRANSACTION_REFERENCE	资金关联不合法	检查关联的交易
410	CURSOR_EXPIRED	游标已过期	按注单记录重新建立读取
412	VERSION_CONFLICT	If-Match 版本不匹配	重新读取后再决定是否提交
413	PAYLOAD_TOO_LARGE	body 超过 1 MiB	缩小请求
422	VALIDATION_FAILED	金额或参数的值不合法，例如精度超过币种的 decimal_scale	修正参数。平台不会自动舍入
422	UNSUPPORTED_CAPABILITY	当前商户或钱包模式不支持该功能	查看 capabilities
422	CURRENCY_NOT_SUPPORTED	币种未开通	使用已开通的币种
422	GAME_NOT_AVAILABLE	游戏未授权、维护中或暂不可启动	查看游戏列表中的 status 和 launch_supported
428	PRECONDITION_REQUIRED	缺少必需的 If-Match	补充请求头
429	RATE_LIMITED	超出调用频率	按 Retry-After 等待。资金请求重试时保持原 ID
500	INTERNAL_ERROR	平台内部错误	资金请求要查单确认，不能直接当作失败
503	DEPENDENCY_UNAVAILABLE	依赖服务暂时不可用，例如商户钱包无法确认余额	资金请求要查单确认，不能直接当作失败

retryable 的含义

retryable=true 只说明这次传输可以重试，不说明钱有没有变化。资金请求重试时必须使用原来的 external_id 和 Idempotency-Key，并换新的 X-Timestamp 重新签名。

调用频率

默认限额（以 capabilities.limits 返回的值为准）：

类别	默认
注单查询	每个商户 2 次/秒
其他查询	每个商户 10 次/秒
写入	每个商户 5 次/秒

商户回调应返回的错误码

单一钱包回调失败时，商户同样返回错误格式。常用的错误码：

场景	HTTP	error.code
凭据或签名校验失败	401	AUTHENTICATION_FAILED
时间戳超出 ±300 秒	401	REQUEST_EXPIRED
玩家不存在	404	RESOURCE_NOT_FOUND
查无此交易（retryable 必须为 false）	404	TRANSACTION_NOT_FOUND
币种不支持	422	CURRENCY_NOT_SUPPORTED
同一 transaction_id 对应了不同的请求内容	409	IDEMPOTENCY_CONFLICT
暂时无法处理	503	DEPENDENCY_UNAVAILABLE

余额不足不要用 HTTP 错误表示，要返回 201，并带 status=FAILED 和 failure.code=INSUFFICIENT_FUNDS，见改变玩家余额。