跳转到主要内容
XPayLabs 使用标准的 R<T> 信封返回错误,带有与 HTTP 兼容的 code 和人类可读的 msg。与传统的支付处理器不同,XPayLabs 错误主要是验证和身份认证错误——由于区块链交易是最终性的,API 层面没有”卡被拒绝”或”余额不足”错误(这些属于区块链层面的问题)。

错误响应格式

字段类型描述
codeinteger与 HTTP 兼容的状态码
msgstring人类可读的错误描述
datanull错误响应中始终为 null

状态码

含义典型原因
400错误请求缺少或无效参数
401未授权HMAC 签名无效或时间戳已过期
422不可处理地址格式对该链无效
429请求过多超出速率限制
500内部错误意外的网关错误

常见验证错误

签名错误 (401)

消息原因
"The sign cannot be left blank."请求中缺少 sign 字段
"Sign verification failed"HMAC 签名与计算值不匹配
"The timestamp cannot be left blank."timestamp 缺失
"The nonce cannot be left blank."nonce 缺失

订单错误 (400)

消息原因
"The amount cannot be left blank."金额缺失或为 null
"The symbol cannot be left blank."代币符号缺失
"The chain cannot be left blank."区块链网络缺失
"The receiveAddress cannot be left blank."付款目标地址缺失
"ReceiveAddress error"地址格式对指定链无效
"The orderId cannot be left blank."V3 商家必需
"The uid cannot be left blank."V2 商家必需
"The uid cannot be zero."uid 被设置为 "0"

在集成中处理错误

速率限制

XPayLabs 对每个端点实施可配置的速率限制。超出限制会返回 429 响应。 默认限制:
端点限制
/order/createCollection每 10 秒每 IP 100 次
/order/createPayout每 10 秒每 IP 100 次
/order/status/{orderId}每 10 秒 1000 次
/order/pay每秒每个 orderId 2 次
/order/getOrderStatus每秒每个 orderId 2 次
/symbol/supportSymbols每 10 秒 50 次
最后修改于 2026年6月26日