错误处理

SDK 错误类型

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

Go 的错误用 errors.As 判别；Java 的四个异常都是非受检的，基类是 WantuPay.PayException。

Node.js

Python

Java

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

try {
  await pay.create_refund({ out_trade_no, out_refund_no, amount })
} catch (err) {
  if (err instanceof WantuPayApiError) {
    // 业务失败：err.code / err.channel_code（渠道原因，仅排障用）
    logger.error('退款失败', { code: err.code, message: err.message })
  } else if (err instanceof WantuPayHttpError) {
    // 网络问题：退款用同一 out_refund_no 重试是安全的
  } 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 重试是安全的
    ...

_, err := pay.CreateRefund(ctx, params)
if err != nil {
	var apiErr *wantupay.APIError
	var httpErr *wantupay.HTTPError
	switch {
	case errors.As(err, &apiErr):
		// 业务失败：apiErr.Code / apiErr.ChannelCode（渠道原因，仅排障用）
		log.Printf("退款失败 code=%d message=%s", apiErr.Code, apiErr.Message)
	case errors.As(err, &httpErr):
		// 网络问题：退款用同一 OutRefundNo 重试是安全的
	default:
		// *ConfigError：入参有问题，请求根本没发出去
	}
}

try {
    pay.createRefund(params);
} catch (WantuPay.ApiException e) {
    // 业务失败：e.code / e.channelCode（渠道原因，仅排障用）
    log.error("退款失败 code={} message={}", e.code, e.getMessage());
} catch (WantuPay.HttpException e) {
    // 网络问题：退款用同一 outRefundNo 重试是安全的
} catch (WantuPay.ConfigException e) {
    // 入参有问题，请求根本没发出去
}

错误码

code	HTTP	含义	处理
40001	401	签名错误	检查 `api_secret` 与签名实现
40002	401	时间戳超窗或重放	校准服务器时间后重试
40003	403	商户不存在或已禁用	联系顽兔
40004	400	参数错误	按 `message` 提示修改
40401	404	单据不存在	检查单号
40901	409	单号冲突（同号不同参数）	更换单号
40902	409	关单时订单已支付	按已支付处理：入账或走退款接口
42201	422	业务不可行：渠道未开通、退款超额等	按 `message` 处理；渠道拒绝时看 `channel_code` 排障
42202	422	`notify_url` 和商户后台的回调配置对不上：统一地址模式下传了，或者地址不在白名单里	去商户后台「接入配置」核对回调方式和白名单，该改配置改配置，该改代码改代码，见支付回调
42901	429	触发限流	退避后重试
50001	500	网关内部错误	查询类重试；下单用原单号重试
50002	502	支付渠道暂不可用	退避后重试

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

重试原则

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

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

#错误处理

#SDK 错误类型

#错误码

#重试原则

错误处理

SDK 错误类型

错误码

重试原则