错误码说明

通用错误码（如 BAD_REQUEST / UNAUTHORIZED）会被多个原因复用，具体原因以 message / messageDetail 字段为准，请勿仅依赖 code 做分支判断。

通用错误码（所有接口 - 签名验证层）

错误码	HTTP 状态码	说明
BAD_REQUEST	400	缺少必要请求头
BAD_REQUEST	400	时间戳格式无效
BAD_REQUEST	400	时间戳超出允许窗口
UNAUTHORIZED	401	无效的 app id
UNAUTHORIZED	401	应用未激活
UNAUTHORIZED	401	商户未激活
FORBIDDEN	403	IP 权限拒绝
UNAUTHORIZED	401	无效的 api secret
UNAUTHORIZED	401	签名无效
INTERNAL_SERVER_ERROR	500	内部服务器错误

---

业务错误码

createPayment - 创建支付订单

错误码	说明
PAYMENT_GET_LOCK_ERROR	系统繁忙，请稍后重试
PAYMENT_DUPLICATE_ORDER	订单已存在
PAYMENT_INVALID_CONFIG	商户网络配置缺失
PAYMENT_INVALID_CONFIG	未找到该币种支持的网络
PAYMENT_INVALID_CONFIG	收款地址未配置
PAYMENT_INVALID_CONFIG	BGW 支付必须指定网络
PAYMENT_INVALID_REQUEST	提供 toAddress 时必须指定网络 (payMethod2)
PAYMENT_INVALID_TO_ADDRESS	该网络的地址格式无效
PAYMENT_INVALID_PAY_METHOD	无效的支付渠道
PAYMENT_INVALID_PAY_METHOD	支付网络必填
PAYMENT_INVALID_PAY_METHOD	请为 {currency} 在 {network} 上添加非中心化钱包

getPaymentStatus - 查询支付状态

错误码	说明
PAYMENT_TRANSACTION_NOT_FOUND	未找到支付交易记录

createRefund - 创建退款

错误码	说明
PAYMENT_GET_LOCK_ERROR	系统繁忙，请稍后重试
PAYMENT_INVALID_PAYMENT_STATE	支付状态不允许退款
PAYMENT_DUPLICATE_REFUND	退款交易重复
PAYMENT_INVALID_REQUEST	退款责任类型不匹配
PAYMENT_INVALID_REQUEST	支付 paidAmount 为空
PAYMENT_INVALID_REQUEST	退款金额超过已付金额
SYS_ERROR	订单已退款
SYS_ERROR	不支持该支付方式的退款
SYS_ERROR	在支付渠道创建退款失败
SYS_ERROR	创建/更新退款失败

getRefundStatus - 查询退款状态

错误码	说明
PAYMENT_REFUND_NOT_FOUND	未找到退款交易记录

trial - 获取汇率报价

错误码	说明
UNSUPPORTED_CURRENCY_PAIR	不支持的币种对
UNSUPPORTED_CURRENCY_PAIR	不允许同币种转换
UNSUPPORTED_CURRENCY_PAIR	币种对必须为法币与稳定币之间
UNSUPPORTED_PAYMENT_CURRENCY	商户不支持该支付币种
MERCHANT_QUOTE_RULE_NOT_FOUND	未找到商户报价规则

商户层级（合作伙伴凭据）

错误码	说明
MERCHANT_ID_REQUIRED	合作伙伴（Partner）凭据调用必须传入 merchantId
MERCHANT_APP_ID_REQUIRED	归属商户存在多个授权应用，必须传入 merchantAppId
MERCHANT_GRANT_INVALID	凭据对所传 merchantId 无有效授权
MERCHANT_STATE_INVALID	目标商户状态不可用