跳到主要内容

错误码

HTTP status 表达本次 API 请求是否成功；body 中的 code/msg 是稳定平台业务码。

排查时请同时记录 HTTP status、code/msg、traceId、请求路径、商户订单号和请求时间。traceId 是定位平台侧日志的关键字段。

响应结构​

{
  "code": 12100007,
  "msg": "INVALID_FIELD",
  "traceId": "7f3d2f0c9b4d4a1a",
  "data": {
    "message": "paymentMethod.pse.bankCode is required"
  }
}

业务码​

HTTP 200200OK

成功。

HTTP 40012100007INVALID_FIELD

参数错误、JSON 格式错误或未知字段。

HTTP 40012100008UNSUPPORTED_CURRENCY

不支持的币种。

HTTP 40012100009UNSUPPORTED_METHOD

不支持的 method 或 currency/method 组合。

HTTP 40112100010UNAUTHORIZED

签名缺失、签名错误、时间戳过期或密钥未配置。

HTTP 40212100011INSUFFICIENT_BALANCE

余额不足。

HTTP 40312100012METHOD_NOT_ENABLED

method 存在但商户未开通。

HTTP 40412100013ORDER_NOT_FOUND

订单不存在。

HTTP 404404NOT_FOUND

订阅对象不存在，或不属于当前商户。

HTTP 40912100014IDEMPOTENCY_CONFLICT

订单场景：单号已被占用但平台取不回那笔订单。订阅接口：本次请求与首次使用同一 merchantPlanNo / merchantSessionNo / clientRequestId 的请求不一致，或当前资源状态不允许该操作。

HTTP 42912100015RATE_LIMITED

请求限流。

HTTP 50012100016INTERNAL_ERROR

内部异常。

HTTP 50312100017SERVICE_UNAVAILABLE

依赖服务不可用或上游超时。

HTTP 50312100020CHANNEL_BUSY

支付渠道临时限流。订单未创建：退避后用同一个 merchantOrderNo 重发同一请求，不需要先查询。

旧错误码仍可能出现在历史接口或后台接口中；本 Merchant API 以本页为准。

处理建议​

INVALID_FIELD

按 data.message 修正字段、格式、method 分支或必填项。

UNAUTHORIZED

检查 Access Key、Ed25519 私钥与已上传公钥是否匹配、created/expires 时间窗口、nonce 是否重复、Content-Digest 和平台 body key id。

IDEMPOTENCY_CONFLICT

merchantOrderNo 已被占用但平台取不回那笔订单。继续按该单号查询，不要换号。下单接口从不比对字段，所以这个码不代表请求内容有差异。

RATE_LIMITED

降低请求频率，避免短时间重复查询同一订单。

5xx / connection broken

不要直接换单重试，先用查询接口确认订单是否已创建。

Subscription API：HTTP 与 Operation​

订阅创建和变更接口可能以 HTTP 200 返回 operation。HTTP status 表达 API 调用层，operation.status 表达已经记录的副作用操作层。即使 HTTP 为 200，FAILED、CHANNEL_UNKNOWN、PENDING、RUNNING 也不能按 Operation 成功处理。

订阅接口与下单接口不同：它会把本次请求与首次使用同一 merchantPlanNo、merchantSessionNo 或 clientRequestId 的请求做比对，不一致就返回 IDEMPOTENCY_CONFLICT；当前资源状态不允许操作时也返回同一个码。应先查询原订阅对象。

HTTP 500、503 的 data.message 使用固定脱敏文案。请记录 traceId、对应商户业务号以及存在时的 operationNo；不能更换业务号盲目创建重复对象。