R<T> 信封返回错误,带有与 HTTP 兼容的 code 和人类可读的 msg。与传统的支付处理器不同,XPayLabs 错误主要是验证和身份认证错误——由于区块链交易是最终性的,API 层面没有”卡被拒绝”或”余额不足”错误(这些属于区块链层面的问题)。
错误响应格式
| 字段 | 类型 | 描述 |
|---|---|---|
code | integer | 与 HTTP 兼容的状态码 |
msg | string | 人类可读的错误描述 |
data | null | 错误响应中始终为 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 次 |

