● 错误码自查 · 33 业务码 + 20 拒付码

错误码自查

一次调用有三层码,分别回答三个不同的问题。九成的对接问题是把这三层混成一层。

先分清三层

层回答什么看哪里
HTTP 层这次调用我们受理了吗200 / 4xx / 5xx
业务层请求本身有没有问题biz_code + code
支付结果层钱到底扣成没有attempt.unified_code

HTTP 200 不等于支付成功。渠道拒付时 HTTP 是 200、没有 code 字段,失败信息在 status 和 attempts[].unified_code 里。用状态码判断支付结果是最常见、也最贵的接错方式。

业务错误码号段

biz_code 是四位数字,和字符串 code 一一对应。数字用来写 switch 分支,字符串用来写日志和工单——两个都给是为了让你不用维护一张映射表。

{
  "code": "refund_exceeds_captured",
  "biz_code": "4012",
  "message": "refund amount exceeds captured amount",
  "details": [{ "field": "amount", "reason": "max_refundable_is_6900" }],
  "request_id": "req_3f9a2c"
}
号段类别处理方向
0成功不是错误。HTTP 2xx 且无 code 字段
1xxx鉴权与签名密钥、签名、时间戳、nonce、环境。改配置,别重试
2xxx参数校验请求体本身不合法,details 指到字段。改了再发
3xxx幂等与并发Idempotency-Key 缺失或冲突
4xxx业务状态不允许对象当前状态做不了这个动作。先查状态和 available_actions
5xxx渠道与路由渠道拒付、超时、不支持、全部不可用
6xxx配额与限流超商户配额。立刻停,按 Retry-After 退避
9xxx系统内部我们的问题。带 request_id 报障,同 key 退避重试安全

业务错误码全表

这些都带 code 字段返回,说明请求没能进入支付流程。

biz_codecodeHTTP可重试原因怎么自查
4002 refund_not_found 404 否 退款单不存在,或属于另一个环境 退款单号是 RF 开头,不要和支付单号 PY 搞混
4021 payout_not_cancellable 409 否 出款已提交渠道,撤不回来了 只有 created(等审批)状态能撤。已 processing 的只能等结果,失败会自动退回余额
4040 file_too_large 413 否 单个文件超过 10 MB 举证材料先压缩。多份材料分多次上传,evidence 接口可以带多个 file_id
4041 file_type_unsupported 400 否 文件类型不在白名单 只收 pdf / jpg / png / tiff。卡组织不接受其他格式,我们提前拦掉而不是让你败诉
4050 routing_version_conflict 409 否 发布时带的 version 不是当前版本,说明有人在你之前改过 重新 GET 拿最新规则集,合并你的改动再提交。这是乐观锁,不是故障
4051 routing_invalid_rule 400 否 规则引用了不存在或已下线的渠道,或条件字段拼错 先用 POST /v1/routing/simulate 干跑一遍。不要直接发布到 live
4060 export_not_ready 409 是 导出任务还在跑 轮询 GET /v1/finance/exports/{uid} 等 status=ready,或订阅回调。大批量导出通常几十秒
4070 webhook_url_insecure 400 否 回调地址不是 https,或指向内网/保留地址 必须是公网可达的 https。我们不会往 http 投递签名事件
1001 auth_key_missing 401 否 请求没带 Authorization 头,或格式不是 Bearer 确认头是 Authorization: Bearer sk_live_xxx,Bearer 后有一个空格
1002 auth_key_invalid 401 否 密钥不存在、已吊销,或被 GitHub 密钥扫描自动吊销 控制台「开发者 → API 密钥」看这把 key 的状态;被自动吊销说明它已泄漏到公开仓库,必须换新的
1003 auth_env_mismatch 401 否 用 sk_test_ 打了 live 域名,或反过来 密钥前缀必须和域名环境一致。这条拦的是「测试代码打到生产」,不要改配置绕过
1010 auth_signature_invalid 401 否 签名算错。九成是请求体被重新序列化过 对发出去的原始字节算 SHA-256,不要把对象反序列化再 stringify;检查六段顺序与分隔符是换行
1011 auth_timestamp_expired 401 是 X-Timestamp 与服务端偏差超过 ±300 秒 校准服务器 NTP,不是把窗口调大
1012 auth_nonce_replayed 401 否 同一个 X-Nonce 在 10 分钟内重复使用 nonce 每次请求重新生成;重试时换 nonce 和时间戳,但 Idempotency-Key 保持不变
1020 auth_browser_origin_rejected 401 否 请求带了浏览器的 Origin / Referer 头,说明 secret key 出现在前端 立刻吊销这把 key。开放 API 只能从服务端调,前端用 publishable key + client token
2001 validation_failed 400 否 参数不合法,details 指到具体字段 按 details[].field 和 reason 改。金额是最小币种单位的正整数,不是小数
2010 validation_currency_unsupported 400 否 币种未开通,或该币种下没有可用通道 控制台「渠道 → 能力矩阵」看这个币种有没有已启用的通道
2020 validation_encrypted_field_required 400 否 卡号、CVV、收款账号以明文提交 这类字段必须走数字信封(encrypted 对象)或 JWE,明文一律拒收
3001 idempotency_key_missing 400 否 POST 没带 Idempotency-Key 所有 POST 都要带,建议 UUID / ULID
3002 idempotency_key_conflict 409 否 同一个 Idempotency-Key 配了不同的请求体 这是在保护你——改了金额就换 key。沿用旧 key 说明 key 没和业务单号绑定
4001 payment_not_found 404 否 支付单不存在,或属于另一个环境 / 另一个商户 确认 uid 没拼错、当前密钥环境与建单时一致
4010 payment_not_capturable 409 否 状态不是 authorized,或 capture_mode 不是 manual 先看 available_actions,它是后端算好的,比自己判断 status 可靠
4011 payment_not_refundable 409 否 未扣款,或已过渠道允许的退款窗口 未扣款的单用 void 撤销授权,不要用退款
4012 refund_exceeds_captured 409 否 退款累计额超过已扣款额 服务端用一条带条件的 UPDATE 拦的,并发重复提交不会超退。你按 captured_amount - refunded_amount 算可退额
4013 payment_already_terminal 409 否 单子已是 failed / cancelled 终态 终态不可逆。迟到的成功回调不会翻单,要翻走人工补偿
5001 connector_declined 200 视情况 渠道拒付。看 attempt 的 unified_code 与 decline_type soft 我们已自动级联,你不用重试;hard 永不重试,重试只会加剧风控
5002 connector_timeout 200 否 渠道超时,结果未知 这不是失败。别当失败重试(可能重复扣款),调查询接口收敛,或等对账补偿
5010 connector_unsupported_operation 409 否 该渠道不支持这个操作(如调整授权金额) 控制台「渠道 → 能力矩阵」确认该渠道支持哪些动作
5011 connector_unavailable 503 是 全部候选渠道不可用,或熔断器已打开 看控制台「渠道健康」。退避后用同一个 Idempotency-Key 重试
4020 payout_approval_required 202 否 金额超过阈值,进了双人复核 不是错误。审批通过后会推 payout.status_changed 回调
4030 dispute_evidence_window_closed 409 否 已过 evidence_due_at 举证窗口由卡组织规定,过期不可补。把 dispute.opened 回调接上并设提醒
6001 rate_limited 429 是 超出商户配额 立刻停,按 Retry-After 等待。继续打会被临时封禁
9001 internal_error 500 是 我们这边的问题 带上 request_id 报障。同 Idempotency-Key 退避重试是安全的

可重试=是 的前提是带同一个 Idempotency-Key。换 key 重试等于新开一笔,在支付里就是重复扣款。

统一拒付码(响应 200,支付失败)

渠道拒付不是接口错误,所以 HTTP 是 200、code 字段不存在。每个渠道的原始拒付码都不一样,我们统一映射成 unified_code,跨渠道可比、可统计、可配路由规则。

HTTP/1.1 200 OK      ← 调用成功了

{
  "uid": "PY20261116000217A7F3",
  "status": "failed",            ← 是这笔支付没成
  "is_terminal": true,
  "attempt_count": 2,
  "attempts": [
    { "attempt_no": 1, "connector_code": "stripe",
      "status": "failed", "provider_code": "05",
      "unified_code": "do_not_honor", "decline_type": "soft" },
    { "attempt_no": 2, "connector_code": "adyen", "is_fallback": true,
      "status": "failed", "provider_code": "51",
      "unified_code": "insufficient_funds", "decline_type": "soft" }
  ]
}

两种拒付,处理方式完全相反

soft可能换个渠道就过。我们已自动级联到备用通道,你不要再重试——重复的只会是重复扣款风险。
hard换谁都不会过。我们直接终止级联。你重试只会拉高欺诈率、触发发卡行锁卡。

soft · 软拒(8 个)

biz_codeunified_code含义典型渠道原码怎么办
5101insufficient_funds 余额/额度不足Stripe card_declined · Visa 51 级联到备用渠道无用(同一张卡)。提示买家换卡或稍后再试
5102do_not_honor 发卡行拒绝但不说原因,最常见的一类Visa 05 · Adyen Refused 最值得级联:换收单渠道后常能过。我们默认自动级联
5103issuer_unavailable 发卡行系统不可用Visa 91 自动级联。全渠道都返这个说明是发卡行侧故障
5104processing_error 渠道或发卡行处理异常Visa 96 自动级联
5105exceeds_limit 超出单笔或累计限额Visa 61 / 65 提示买家分次支付或换卡。级联无用
5106velocity_limit 短时间内尝试次数过多Visa 65 停止重试。继续打会触发发卡行风控锁卡
5107try_again_later 发卡行要求稍后重试Adyen Acquirer Error 自动级联;全失败则让买家稍后再试
5108three_ds_required 发卡行要求 3DS 验证Visa 1A 不是失败。按 attempt.action 跳转,完成后调 resume

hard · 硬拒(11 个,一律不重试)

biz_codeunified_code含义典型渠道原码怎么办
5201authentication_failed 3DS 验证失败或被买家放弃Adyen AuthenticationFailure 不重试。让买家重新发起支付
5202lost_or_stolen_card 卡已挂失或被盗Visa 41 / 43 绝对不重试。重试会被记录为可疑行为
5203pickup_card 发卡行要求收缴此卡Visa 04 / 07 绝对不重试
5204expired_card 卡已过期Visa 54 提示买家更新有效期。已绑卡应触发换卡流程
5205invalid_card_number 卡号不存在或校验失败Visa 14 检查卡号采集逻辑。绑卡 token 报这个说明卡已注销
5206account_closed 账户已关闭Visa 78 / 79 不重试。删除该绑卡 token
5207restricted_card 该卡被限制使用此类交易Visa 62 常见于跨境、虚拟商品。换币种或走本地渠道可能可行
5208transaction_not_permitted 发卡行不允许此类交易Visa 57 同上。检查 MCC 与渠道的匹配
5209fraud_suspected 渠道或发卡行判定为欺诈Visa 59 · Adyen FRAUD 绝对不重试,并检查这笔订单。重试会拉高你的欺诈率
5210blocked_by_rule 命中你自己配的风控规则或 BIN 黑名单— 不是渠道拒的。控制台「风控」里查是哪条规则
5211currency_not_supported 该渠道不支持此币种— 路由配置问题,不是买家问题。检查渠道能力矩阵

既不是软拒也不是硬拒

biz_codeunified_code含义典型渠道原码怎么办
5002connector_timeout 渠道超时,结果未知— 不是失败也不是成功。不要重试,调查询接口收敛或等对账

永远不要把 unified_code 或 message 原样展示给买家。fraud_suspected 告诉买家等于告诉盗刷者哪条规则命中了;insufficient_funds 在共享账户场景是隐私泄漏。面向买家只说「支付未成功,请换一种方式」。