● 错误码自查 · 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_code | code | HTTP | 可重试 | 原因 | 怎么自查 |
|---|---|---|---|---|---|
| 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_code | unified_code | 含义 | 典型渠道原码 | 怎么办 |
|---|---|---|---|---|
| 5101 | insufficient_funds | 余额/额度不足 | Stripe card_declined · Visa 51 | 级联到备用渠道无用(同一张卡)。提示买家换卡或稍后再试 |
| 5102 | do_not_honor | 发卡行拒绝但不说原因,最常见的一类 | Visa 05 · Adyen Refused | 最值得级联:换收单渠道后常能过。我们默认自动级联 |
| 5103 | issuer_unavailable | 发卡行系统不可用 | Visa 91 | 自动级联。全渠道都返这个说明是发卡行侧故障 |
| 5104 | processing_error | 渠道或发卡行处理异常 | Visa 96 | 自动级联 |
| 5105 | exceeds_limit | 超出单笔或累计限额 | Visa 61 / 65 | 提示买家分次支付或换卡。级联无用 |
| 5106 | velocity_limit | 短时间内尝试次数过多 | Visa 65 | 停止重试。继续打会触发发卡行风控锁卡 |
| 5107 | try_again_later | 发卡行要求稍后重试 | Adyen Acquirer Error | 自动级联;全失败则让买家稍后再试 |
| 5108 | three_ds_required | 发卡行要求 3DS 验证 | Visa 1A | 不是失败。按 attempt.action 跳转,完成后调 resume |
hard · 硬拒(11 个,一律不重试)
| biz_code | unified_code | 含义 | 典型渠道原码 | 怎么办 |
|---|---|---|---|---|
| 5201 | authentication_failed | 3DS 验证失败或被买家放弃 | Adyen AuthenticationFailure | 不重试。让买家重新发起支付 |
| 5202 | lost_or_stolen_card | 卡已挂失或被盗 | Visa 41 / 43 | 绝对不重试。重试会被记录为可疑行为 |
| 5203 | pickup_card | 发卡行要求收缴此卡 | Visa 04 / 07 | 绝对不重试 |
| 5204 | expired_card | 卡已过期 | Visa 54 | 提示买家更新有效期。已绑卡应触发换卡流程 |
| 5205 | invalid_card_number | 卡号不存在或校验失败 | Visa 14 | 检查卡号采集逻辑。绑卡 token 报这个说明卡已注销 |
| 5206 | account_closed | 账户已关闭 | Visa 78 / 79 | 不重试。删除该绑卡 token |
| 5207 | restricted_card | 该卡被限制使用此类交易 | Visa 62 | 常见于跨境、虚拟商品。换币种或走本地渠道可能可行 |
| 5208 | transaction_not_permitted | 发卡行不允许此类交易 | Visa 57 | 同上。检查 MCC 与渠道的匹配 |
| 5209 | fraud_suspected | 渠道或发卡行判定为欺诈 | Visa 59 · Adyen FRAUD | 绝对不重试,并检查这笔订单。重试会拉高你的欺诈率 |
| 5210 | blocked_by_rule | 命中你自己配的风控规则或 BIN 黑名单 | — | 不是渠道拒的。控制台「风控」里查是哪条规则 |
| 5211 | currency_not_supported | 该渠道不支持此币种 | — | 路由配置问题,不是买家问题。检查渠道能力矩阵 |
既不是软拒也不是硬拒
| biz_code | unified_code | 含义 | 典型渠道原码 | 怎么办 |
|---|---|---|---|---|
| 5002 | connector_timeout | 渠道超时,结果未知 | — | 不是失败也不是成功。不要重试,调查询接口收敛或等对账 |
永远不要把 unified_code 或 message 原样展示给买家。fraud_suspected 告诉买家等于告诉盗刷者哪条规则命中了;insufficient_funds 在共享账户场景是隐私泄漏。面向买家只说「支付未成功,请换一种方式」。