错误码参考 - PayMatrix

本文列出了 OpenAPI 可能返回的错误码及处理建议。

通用响应格式

所有接口在出错时返回统一格式：

{
  "code": 1001015,
  "msg": "param.check.failed",
  "data": null
}

错误码	错误信息	说明	处理建议
1001015	`param.check.failed`	参数校验失败	检查请求参数是否符合规范
1001016	`sign.invalid`	RSA 签名验证失败	检查签名算法和私钥是否正确
1001025	`auth.merchant.sign.params.missing`	缺少必填的签名请求头	检查 4 个签名头是否全部携带
1001026	`auth.merchant.id.invalid`	商户 ID 格式无效	检查 `X-Merchant-Id` 是否正确
1001027	`auth.merchant.not.found.or.key.missing`	商户不存在或公钥未配置	检查商户 ID 或上传 RSA 公钥
1001028	`auth.timestamp.format.invalid`	时间戳格式无效	确保 `X-Timestamp` 为 Unix 毫秒时间戳
1001029	`auth.timestamp.expired`	时间戳超出有效窗口（±2 分钟）	校准服务器时间
1001038	`ip.not.in.whitelist`	客户端 IP 不在白名单内	将当前服务器 IP 加入白名单

错误码	错误信息	说明	处理建议
1001001	`merchant.is.disabled`	商户已被禁用	联系平台处理
1001004	`order.orderAmount.must.be.greater.than.or.equal.to.0.01`	订单金额必须大于等于 0.01	检查金额参数
1001005	`order.already.exists`	商户交易号重复	使用新的 `merchant_transaction_id`
1001008	`order.already.paid.or.canceled`	订单已支付或已取消	检查订单状态，不可重复操作
1001009	`order.not.exists`	订单不存在	检查交易号是否正确
1001010	`order.expired`	订单已过期	订单超时未支付，需重新创建
1001014	`transaction.not.exists`	交易不存在	检查交易 ID 是否正确
1001018	`order.cannot.be.refunded`	当前订单状态不允许退款	检查订单状态是否可退款
1001019	`refund.amount.exceeds.order.amount`	退款金额超出可退金额	调整退款金额
1001020	`order.has.transaction.in.processing`	订单有交易正在处理中	等待当前交易完成后重试
1001024	`transaction.repeat.submit`	重复提交交易	等待上次交易结果
1001036	`pay.in.amount.out.of.range`	入金额度超出范围	检查金额限制
1001037	`pay.in.daily.limit.exceeded`	入金日限额超限	次日重试

对于可重试的错误（如系统错误），建议：