文档目录 · 错误码

错误码

code message_key 说明
10001 error.invalid_api_key API Key 无效或已停用
10002 error.invalid_signature 签名错误
10003 error.timestamp_expired 时间戳已过期
10004 error.nonce_repeated nonce 重复
10005 error.ip_not_allowed 请求 IP 不在白名单
10006 error.permission_denied API Key 未开通该权限
10007 error.channel_api_key_mismatch 通道与 API Key 不一致
10008 error.invalid_merchant_binding 商户与 API Key 不匹配
10009 error.invalid_environment 请求环境与凭证不匹配
10010 error.missing_parameter 缺少必填参数
10011 error.invalid_parameter 参数格式错误
10012 error.unsupported_currency 不支持该币种
10013 error.unsupported_payment_method 不支持该支付类型
10014 error.unsupported_bank 银行或电子钱包不支持 / 无有效映射
10015 error.too_many_requests 请求过于频繁或达到限额
10016 error.risk_rejected 交易被风控拒绝
20001 error.merchant_not_tradeable 商户当前不可交易
20002 error.merchant_not_found 商户不存在
30001 error.channel_unavailable 通道不可用
30002 error.channel_maintenance 通道维护,暂停接收新单;已有正式订单继续处理
30007 error.provider_timeout 支付服务响应超时
30008 error.provider_bad_response 支付服务响应异常
40001 error.insufficient_balance 可用余额不足
40002 error.amount_below_min 金额低于最低限额
40003 error.amount_above_max 金额高于最高限额
40004 error.invalid_amount 金额格式或精度错误
50002 error.submission_conflict 订单或会话创建冲突
50003 error.order_not_found 订单或会话不存在
50006 error.cashier_unavailable 收银台会话或当前配置不可用
50007 error.cashier_expired 收银台会话已过期
50008 error.cashier_selection_conflict 收银台通道或收款资料已锁定
50009 error.cashier_provider_message 收银台提交失败;message 为安全过滤后的支付通道错误信息
90000 error.system_error 系统错误
90001 error.provider_system_error 支付服务暂时异常

自由匹配金额提示#

POST /api/v1/pay/create 与 POST /api/v1/payout/create 使用自由匹配 Key(merchant_global)且未指定 channel_code 时,创建被拒绝后会按当前商户、环境、币种和支付类型的有效绑定通道配置汇总金额边界:最低取所有 min_amount 的最小值,最高取所有 max_amount 的最大值。

例如通道 A 支持 10.00–100.00 MYR,通道 B 支持 20.00–2000.00 MYR,总体最低为 10.00 MYR、最高为 2000.00 MYR。请求金额严格低于最低值时,HTTP 200 响应如下:

{
  "code": 40002,
  "message_key": "error.amount_below_min",
  "default_message": "amount below minimum",
  "message": "amount below minimum (MYR 10.00)",
  "data": null,
  "request_id": "req_example_amount_below_min"
}

请求金额严格高于最高值时:

{
  "code": 40003,
  "message_key": "error.amount_above_max",
  "default_message": "amount above maximum",
  "message": "amount above maximum (MYR 2000.00)",
  "data": null,
  "request_id": "req_example_amount_above_max"
}
  • 本地化只改变 message 文案,币种与金额仍保留;程序使用 code 判断错误,不解析展示文案。
  • 有通道未配置某侧边界时,该侧不限,不提示有限的总体边界。
  • 汇总只取通道配置,不合并 API Key 或商户绑定限额;总体区间内仍须通过各通道、费率、银行、余额等校验。金额位于不同通道之间的区间空档时,继续返回原来的通道不匹配错误。
  • 固定 Key、显式指定通道及已有正式订单重试保持原行为。API Key 自身限额校验、代付余额不足与内部错误优先沿用原错误,不保证所有创建失败都返回金额提示。
  • 金额拒绝不保存新会话、不返回 payment_url,不创建正式订单或冻结资金。

通道维护错误与重试#

30002 / error.channel_maintenance 表示平台因通道维护拒绝本次新单,default_message 为 channel maintenance;它不是订单终态。自由匹配创建会排除维护通道,无合格候选时仍可能返回 30001 / error.channel_unavailable 或其他对应的校验错误,不保证所有维护场景都返回 30002。

收到维护错误时保留原 merchant_order_no,先查询是否已有正式订单;已有订单继续按原状态处理,不更换订单号重复创建。尚未生成正式订单的收银台会话可选择其他合格的 active 通道;若请求已指定 channel_code,不能通过修改该字段重试同一幂等创建请求。再次发送请求须生成新的 timestamp、nonce 和 sign,保持原创建业务参数一致。

发生错误时保存 code、message_key 和 request_id,使用原订单号查询结果。

搜索文档