错误处理

SDK 错误类型

Node.js	Python	含义	处理
`WantuPayConfigError`	`WantuPayConfigError`	本地入参或配置错误，请求未发出	修正参数，不要重试
`WantuPayHttpError`	`WantuPayHttpError`	网络失败或响应异常	查询类接口可重试
`WantuPayApiError`	`WantuPayApiError`	网关返回业务失败，看 `code`	按下方错误码处理
`WantuWebhookVerifyError`	`WantuWebhookVerifyError`	回调验签失败	不处理业务，返回非 2xx

Node.js

Python

import { WantuPayApiError, WantuPayHttpError } from 'wantu-merchant-sdk'

try {
  await pay.refunds.create({ outTradeNo, outRefundNo, amount })
} catch (err) {
  if (err instanceof WantuPayApiError) {
    // 业务失败：err.code / err.channelCode（渠道原因，仅排障用）
    logger.error('退款失败', { code: err.code, message: err.message })
  } else if (err instanceof WantuPayHttpError) {
    // 网络问题：退款用同一 outRefundNo 重试是安全的
  } else {
    throw err
  }
}

from wantu_pay import WantuPayApiError, WantuPayHttpError

try:
    pay.create_refund(out_trade_no=out_trade_no, out_refund_no=out_refund_no, amount=amount)
except WantuPayApiError as err:
    # 业务失败：err.code / err.channel_code（渠道原因，仅排障用）
    logger.error("退款失败 code=%s message=%s", err.code, err)
except WantuPayHttpError:
    # 网络问题：退款用同一 out_refund_no 重试是安全的
    ...

错误码

code	HTTP	含义	处理
40001	401	签名错误	检查 `api_secret` 与签名实现
40002	401	时间戳超窗或重放	校准服务器时间后重试
40003	403	商户不存在或已禁用	联系顽兔
40004	400	参数错误	按 `message` 提示修改
40401	404	单据不存在	检查单号
40901	409	单号冲突（同号不同参数）	更换单号
42201	422	业务不可行，如退款超额	看 `channel_code` 排障
42901	429	触发限流	退避后重试
50001	500	网关内部错误	查询类重试；下单用原单号重试
50002	502	支付渠道暂不可用	退避后重试

channel_code 与 channel_message 只用于排障展示，业务逻辑不要依赖它们。

重试原则

查询类接口失败可以直接重试
下单、退款用原单号重试，不会产生重复订单或重复退款
40001 到 40004 是配置或参数问题，重试无效，修正后再调

按症状定位问题走常见问题排查。

#错误处理

#SDK 错误类型

#错误码

#重试原则

错误处理

SDK 错误类型

错误码

重试原则