错误码说明

开放 API 统一使用 code/message/data 外包装。成功时 code=0。参数、鉴权、限流、系统类错误使用数字 code；业务失败使用字符串业务码，并且 HTTP 状态通常仍为 200。

通用响应

HTTP	code	含义	处理建议
400	`40001`	参数格式错误	查看 `data.fields`，按字段修正请求体或 query 参数。
401	`40100`	鉴权失败	查看 `message` 区分 App ID、签名、时间戳、Nonce；重新生成签名后重试。
403	`40300`	来源 IP 未授权	在商户后台维护服务器出口 IP 白名单，或联系平台运营。
429	`42902`	请求过于频繁	按响应头 `Retry-After` 退避重试。
500	`50000`	平台内部错误	保留请求时间、商户订单号、请求 ID，联系平台排查。

参数错误字段明细

{
  "code": 40001,
  "message": "参数格式错误：currency 长度必须为 3",
  "data": {
    "fields": [
      {
        "field": "currency",
        "rule": "len",
        "param": "3",
        "message": "currency 长度必须为 3",
        "value": "__CURRENCY_CODE__"
      }
    ]
  }
}

常见规则：required 必填、len 固定长度、min/max 长度或数值范围、gt/gte/lt/lte 数值比较、oneof 枚举值、url URL 格式。敏感字段如账号、证件号、手机号会脱敏为 ****。

鉴权失败 message

message	常见原因	处理建议
应用ID不存在	`X-App-Id` 不存在、已重置或填错环境	确认使用线上商户后台生成的 App ID / App Secret。
签名校验失败	App Secret 错误、请求体签名前后不一致、签名算法错误	优先使用文档页右上角自动签名，或用签名工具核对原始 body。
时间戳超出允许范围	`X-Timestamp` 与服务器相差超过 60 秒	先调用 `/api/v1/merchant/timestamp` 校时。
随机数格式错误	`X-Nonce` 不是 32 位英文字母或数字	每次请求生成新的 32 位随机字符串，并重新签名。
随机数已使用过，请重试	同一 App ID 下 Nonce 在 5 分钟内重复	重新生成 Nonce 并重签。

业务错误码

code	含义	处理建议
`BIZ_DUPLICATE_ORDER_NO`	商户订单号重复	查询原订单结果；不要用同一商户订单号发起不同业务。
`BIZ_INSUFFICIENT_BALANCE`	商户可用余额不足	充值或降低代付金额后重试。
`BIZ_ORDER_NOT_FOUND`	订单不存在或不属于当前商户	检查订单号类型和商户凭据是否匹配。
`BIZ_MERCHANT_FROZEN`	商户被冻结	联系平台运营处理。
`BIZ_MERCHANT_CANCELLED`	商户已注销	停止请求该商户凭据。
`BIZ_DAILY_LIMIT_EXCEEDED`	超过单日限额	降低请求金额或联系平台调整限额。
`BIZ_PAYEE_INFO_INVALID`	收款信息非法	检查收款账号、户名、银行扩展字段。
`BIZ_NOTIFY_URL_INVALID`	回调地址非法	使用公网 HTTPS 地址，避免内网、本机、不可达地址。
`PARAM_SPECIAL_FEE_INVALID`	特殊手续费参数组合非法	关闭时金额传 0 或省略；启用时同时传大于 0 的 `special_fee_amount`。
`BIZ_SPECIAL_FEE_EXCEEDS_AMOUNT`	手续费合计达到或超过订单金额	降低特殊手续费，确保常规手续费与特殊手续费之和小于订单金额。
`BIZ_PERSONAL_NOT_ACTIVE`	个人商户未激活	等待开户/入驻成功，或检查个人信息。
`BIZ_UPSTREAM_ACCOUNT_MISSING`	上游账户参数缺失	检查商户或渠道上游参数配置。
`BIZ_REFUND_ORIGINAL_NOT_REFUNDABLE`	原代收单非支付成功状态，不可退款	只有 success 状态的代收单可退。
`BIZ_REFUND_ORDER_TOO_NEW`	代收创建或支付成功未满 1 分钟	冷静期结束后复用原请求参数发起退款。
`BIZ_REFUND_AMOUNT_EXCEEDED`	累计退款金额超过原单金额	读取 `data.max_refund_amount`，按当前可退上限调整退款金额。
`BIZ_REFUND_NOT_SUPPORTED`	当前渠道不支持退款	联系平台处理。
`BIZ_REFUND_LIANLIAN_FULL_ONLY`	连连渠道订单仅支持全额退款	refund_amount 改为原单金额后重新发起。
`BIZ_REFUND_LIANLIAN_ALREADY_SHARED`	订单已进入分账流程，无法原路退款	转走代付渠道退款，完成后联系平台在原单打外部退款标记。
`BIZ_REFUND_LIANLIAN_FEE_INSUFFICIENT`	未分账余额不足以承担退款手续费	连连全额退款追收原收款费+退款费两笔；待有新的未分账入账后重试或联系平台。
`BIZ_REFUND_LIANLIAN_PAYTYPE_UNSUPPORTED`	原单支付方式缺失或连连不支持原路退回	联系平台人工处理。
`BIZ_REFUND_EXTERNAL_ALREADY_MARKED`	订单已通过其他方式退款（已打外部退款标记）	勿重复发起退款。
`CHANNEL_UNAVAILABLE`	暂无可用渠道	检查渠道启用状态、商户白名单、路由策略。
`CHANNEL_NOT_IN_WHITELIST`	渠道不在商户白名单	不指定渠道或在后台给商户开放该渠道。
`CHANNEL_UPSTREAM_TIMEOUT`	上游超时	等待平台查单收敛，不要盲目重复下单。
`CHANNEL_UPSTREAM_REJECTED`	上游拒绝受理	查看订单失败原因，修正字段或渠道参数后新下单。

汇聚独立接口与兼容规则

/api/v1/merchant/joinpay/payout 创建、代付查单和 /joinpay/feecalc 业务拒绝返回 HTTP 200 + 字符串 code，message 按语言翻译；请按 code 判断，勿以 HTTP 200 判断付款成功。参数绑定错误仍为 HTTP 400/code40001，未认证为 HTTP 401/code40100，未知系统错误为 HTTP 500/code50000。汇聚参数绑定错误不保证返回 data.fields。

余额接口有独立的历史约定：当前开户或所选账户不存在返回 HTTP 404/40400，不是代付查单的 HTTP 200/BIZ_ORDER_NOT_FOUND。显式资金池账号为空、有首尾空白或超过 64 字节返回 HTTP 400/40001；金额合计溢出返回 HTTP 200/joinpay_balance_overflow。所有资金池查询均限定认证商户。

code（HTTP 200）	含义	处理建议
`joinpay_scene_invalid`	收款场景或参数非法	仅支持 A_NATIVE、T_NATIVE、T_JSAPI、T_MINIAPP；检查 wx_data 对象/JSON 字符串、sub_openid 与旧 q5_OpenId 冲突及 sub_appid 是否匹配后台配置。
`joinpay_payout_invalid`	银行卡代付参数或金额计算非法	检查姓名、8–32 位银行账号、对公 12 位联行号、通知地址；试算还需检查整数范围及内扣后到账金额大于 0。HTTP 层绑定错误仍为 400。
`joinpay_payout_conflict`	原单参数不一致，或订单号被既有提现占用/历史订单使用	先查询原业务订单；同一汇聚原单重试必须保持原号、渠道、金额、币种、收款信息和通知地址，不复用旧提现订单号。
`BIZ_ORDER_NOT_FOUND`	汇聚代付查单未找到本商户订单；创建也可能因相关记录缺失返回此码	查单使用原 merchant_order_no 和正确商户凭据；创建则检查渠道/开户等配置。
`payout_channel_not_configured`	试算未找到启用且挂载的汇聚代付渠道或相应费用配置	核对确切 channel_code、商户挂载、渠道类型及启用状态。
`joinpay_channel_credentials_invalid`	汇聚渠道凭据或状态不可用	联系平台核对渠道启用状态和资金池配置。
`joinpay_onboard_required`	汇聚交易商户登记未启用或不完整	先登记并启用汇聚交易商户号。
`joinpay_funds_account_mismatch`	渠道与商户/历史订单资金池不匹配	核对原资金池归属，不跨池转移历史订单。
`joinpay_payout_config_invalid`	产品、用途或代付费用配置不完整	联系平台修正配置；试算成功也不保证所有实际创建前置条件都满足。
`joinpay_payout_result_invalid`	上游结果与原订单不符	保留原订单号并查单/联系平台核查，不能直接视为未付款而换号重付。
`joinpay_balance_insufficient`	对应汇聚资金池可用余额不足	查询本商户对应资金池并补足余额，试算及 max_refund_amount 均不是余额保证。
`joinpay_reconciliation_blocked`	同资金池可取资金不足或核对不满足资金门禁	联系平台核对资金池真实可取金额；试算不检查或预留该资金。
`joinpay_balance_overflow`	汇聚账务金额超出支持范围	联系平台核查，不能忽略错误或按截断金额处理。

代付状态 created/processing/unknown 均非终态。未知结果请通过 GET /api/v1/merchant/joinpay/payout/{merchant_order_no} 查单；只有 success 确认付款到账。旧微信提现入口、统一查单及 completed 状态保持原业务，不能透明切换到汇聚银行卡代付。

汇聚退款继续使用原退款接口：成功及处理中退款累计不超过原订单实收金额；原订单资金池可用余额须足够，平台手续费不退。max_refund_amount 是累计可退上限，不保证实时余额足够。此规则不改变连连、汇付既有退款合同，也不表示银行卡代付支持原路撤回。