Appearance
错误码总表
| code | HTTP | 含义 | 处理建议 |
|---|---|---|---|
0 | 200 | 成功 | — |
| 400xxx — 通用参数 | |||
400001 | 400 / 200 | 参数错误 | HTTP 400 = 请求体未通过结构校验(字段缺失 / 类型错);HTTP 200 = 请求体合法但业务规则不通过(如 settlementMode 与渠道授权不一致)。无论哪种,均查看 message 补全字段或修正取值 |
400002 | 200 | 参数解密失败 | 检查 aesKey 是否 base64 解码后使用;算法 AES-256-CBC + PKCS5 Padding + 16 字节 IV |
| 401xxx — 鉴权 | |||
401001 | 401 | accessToken 无效或已过期 | 重新调用 /openapi/v1/auth/token |
401002 | 401 | 签名校验失败 | 对照 签名与字段加密 拼装规则比对 signText 与 signature |
401003 | 401 | 时间戳偏差超过 ±5 分钟 | 服务器开启 NTP 校时 |
401004 | 401 | nonce 重放 | 每次请求生成新的 32 位 hex 随机串 |
| 403xxx — 权限 | |||
403001 | 200 | 渠道未开通对应接口 | 接口模块级未授权(如未开通 payments/refund)。SPU 维度授权失败应返回 420006,二者边界:403001 = 接口未开通;420006 = 接口已开通,但 SPU 不在该渠道授权列表内 |
403002 | 403 | IP 不在白名单 | 向 BD 提交出口 IP(CIDR 列表) |
403003 | 200 | 支付通道未授权 | paymentChannelCode 不在该渠道授权列表内;调 payment-channels/list 获取合法取值,或联系 BD 开通 |
403004 | 200 | 协议共享未开通 | sharedAgreement.paymentChannelCode 对应通道在 payment-channels/list 中 shareEnabled=false;需双方与支付机构完成协议共享对接 |
| 404xxx — 资源 | |||
404001 | 200 | 资源不存在 | 核对 ID / Code |
| 409xxx — 冲突 | |||
409001 | 200 | 幂等冲突 | 同 Idempotency-Key 不同请求体;请保证前后请求体完全一致,或换新 key |
| 410xxx — 协议(签约) | |||
410001 | 200 | 协议不存在 | 核对 bindOrderNo |
410002 | 200 | 协议未绑卡或绑卡未成功 | 完成 bind-sms + bind-confirm 流程 |
410003 | 200 | 协议已解约 | 需用户重新绑卡 |
410004 | 200 | 绑卡失败 | 通常是验证码错误或通道返回失败,详情见 failReason |
410005 | 200 | 验证码发送失败 | 银行预留手机号无效或通道侧异常 |
410006 | 200 | 共享协议号不存在 | 核对上游订阅是否成功 |
410007 | 200 | 共享协议替换失败 | 详情见 message |
410008 | 200 | 当前订阅不允许替换共享协议 | 仅 A.2(agreementSource=SHARED_FROM_CHANNEL)订阅可调用 agreements/replace;A.1 订阅需用户重新绑卡;B 模式由渠道自管 |
410010 | 200 | 渠道用户手机号与首次绑定不一致 | 同 (channelId, channelUserId) 再次调用 bind-sms / orders/create 入参 mobile 必须与首次绑定一致;如需修改请联系 BD 人工处理 |
410011 | 200 | 该手机号在当前渠道已被其他用户占用 | 同渠道内 (channelId, 手机号) 全局唯一,不允许多个 channelUserId 共用一个手机号 |
| 420xxx — 主订单 | |||
420001 | 200 | 主订单不存在 | 核对 orderNo / externalOrderNo |
420002 | 200 | externalOrderNo 已存在 | 改用新 externalOrderNo,或调用查询接口确认现有订单 |
420003 | 200 | 主订单已解约 | 不可再次解约或修改 |
420004 | 200 | 主订单已完结 | 全部期次已结清 |
420005 | 200 | SPU 不存在或已下架 | 核对 productCode,必要时联系 BD |
420006 | 200 | SPU 对该渠道未开放 | 接口已开通,但本次 productCode 不在该渠道授权列表内,联系 BD 开通该 SPU(与 403001 边界见上) |
420007 | 200 | 订阅周期与 SPU 配置不一致 | 入参 periodType / period / totalCycles 与 SPU 的预设不一致;一个 SPU 仅对应一组周期定价,不同期数请使用对应的独立 productCode |
420008 | 200 | 首扣异步处理中,暂不能解约 | 主订单处于 INITIALIZING(首扣 PROCESSING),解约会与异步扣款竞态。等首扣 webhook 落定后再发起:SUCCESS → ACTIVE 可解约;FAIL → TERMINATED 无需解约 |
| 430xxx — 扣款 | |||
430001 | 200 | 扣款子订单不存在 | 核对 paymentOrderNo |
430002 | 200 | 扣款状态不允许该操作 | 详情见 message(可能已扣款或已退款) |
430003 | 200 | 支付通道返回失败 | 详情见 failCode / failReason,可联系 BD 走退款或重试 |
430004 | 200 | 支付通道超时 | 不要盲目重试,先调查询接口确认真实状态 |
| 429xxx — 限流 | |||
429001 | 429 | 通用限流 | 退避重试 |
429002 | 429 | 渠道每分钟调用次数超限 | 默认 600/min,如需提升联系 BD |
| 451xxx — 公证服务 | |||
451010 | 200 | 公证收费超出区间 | notaryFeeCent 必须在合同约定的最小 / 最大金额区间内;联系 BD 调整授权区间 |
| 500xxx — 系统 | |||
500000 | 500 | 系统异常 | 安全重试一次,问题持续则带 requestId 联系技术 |
500001 | 200 | 上游服务异常 | 通常是上游通道侧故障,详情见 message |
公证函下载路径错误码
公证函下载 GET /notary-cert/access?... 在签名校验 / 参数校验 / 公证函未就绪等情况下,通过 Content-Type 区分成功 / 失败:application/pdf 即成功(PDF 字节流);application/json 即错误。
| code | HTTP | Content-Type | 含义 | 处理建议 |
|---|---|---|---|---|
400001 | 401 | application/json | 订单号格式非法(notaryOrderNo 非数字) | 检查 notaryOrderNo 参数是否为完整数字 ID;若 URL 整体被截断 / 其他参数缺失,响应可能进入通用错误路径而非本码 |
401002 | 401 | application/json | 签名错误 | URL 可能被改动;重新调 公证查询 拿原始 URL |
401005 | 401 | application/json | 访问链接已过期 | 重新调 公证查询 拿新 URL |
450010 | 200 | application/json | 公证函未就绪 | 稍后重试 |
450020 | 200 | application/json | 公证服务暂时不可用 | 稍后重试;持续失败联系 BD |
调用方应先按
Content-Type判断:application/pdf即成功;application/json时再读 JSONcode字段分支处理。
处理 checklist
- 所有错误响应均带
requestId,排查时务必附上 - 5xx 可安全重试一次;4xx 不要重试,属于业务错误
- 401xxx 出现时:核对
timestamp/nonce/signature三个字段的原始值 - 410xxx 出现时:重新走绑卡流程,或调用查询接口确认协议状态
- 429xxx 出现时:依据响应
message区分 IP 段限流与渠道分钟级限流,按建议退避