跳至主要內容

Customer RAG

大约 14 分钟

Customer RAG

适用说明

  • 适用对象：客服、运营人员
  • 用途：根据商户返回的 code 和 responseCode 快速定位问题，给出处理建议
  • 开发者文档：标准 code 含义与集成实践请参阅 错误响应代码

占位符说明

以下为外部系统实际收到的全部错误码。{1} 为动态占位符，实际返回时会被具体内容替换。

未收录的 code

本手册未单独展开 code = "01"（处理中）与 code = "15"（超时）。请参阅 错误响应代码，并通过状态查询 API 确认订单进度。

认证类错误排查可参考 签名生成指南。

responseCode 解码规则

responseCode 为 7 位字符串，由三部分拼接：

responseCode = HTTP状态(3位) + 服务编码(2位) + caseCode(2位)

服务编码对照

服务编码API 路径说明
90v2.0/transaction/pay-in收款
91v2.0/disbursement/pay-out代付
92v2.0/inquiry-status状态查询

code 与 HTTP 状态对照

codeHTTP 状态前缀分类
00200成功
10400请求参数异常
11404目标资源不存在
12401身份认证失败
13429请求频率超限
14403交易被禁止
16400账户余额不足
20502外部通道异常
99500系统内部异常

快速索引

按 code 归类的主索引表。message 级别细分见 错误码明细。

coderesponseCode 示例分类一级处理处理层级详情
0020090xx / 20091xx / 20092xx成功无需处理客服自助#code-00
1040090xx / 40091xx / 40092xx参数异常根据 message 定位字段客服自助#code-10
1140490xx / 40491xx / 40492xx资源不存在确认路径或商户 ID客服自助#code-11
1240190xx / 40191xx / 40192xx认证失败检查签名 / Token客服自助 → 技术支持#code-12
1342990xx / 42991xx / 42992xx请求频繁降频或查订单状态客服自助#code-13
1440390xx / 40391xx / 40392xx交易被禁止必须看 message 判断视场景转派#code-14
1640090xx / 40091xx / 40092xx余额不足告知商户充值客服自助#code-16
2050290xx / 50291xx / 50292xx外部通道异常稍后重试客服自助 → 技术支持#code-20
9950090xx / 50091xx / 50092xx系统异常记录报文转技术支持#code-99

错误码明细

code = "00" — 成功

responseCodemessage服务处理建议
2009000Successful收款请求成功受理，无需处理
2009100Successful代付请求成功受理，无需处理
2009200Successful状态查询请求成功受理，返回订单状态

code = "10" — 请求参数异常

商户最常见的错误，客服可直接处理。

字段格式无效 / 参数无效（caseCode = 01）

收款（serviceCode = 90）
responseCodemessage触发场景处理建议
4009001Invalid Field Format [{1}]Gateway 校验：时间戳格式错误、orderNo 含特殊字符、商户 ID 不一致检查时间戳格式（24 小时内）；orderNo 只含字母、数字、下划线、连字符；请求头与请求体的商户 ID 一致
4009001Invalid request parameter: [{1}]Trade 校验：请求体参数不符合 Bean Validation 规则根据 {1} 中的字段名修正请求参数
4009001Unsupported area [{1}]请求的地区不在支持范围内确认该地区是否已开通支付服务
4009001Unsupported currency [{1}]请求的币种不在支持范围内确认该地区支持的币种列表
4009001Currency does not match area请求币种与地区不匹配修改币种为该地区支持的币种
4009001Duplicate pay order代收订单号重复先查询该 orderNo 的订单状态，如已成功无需再提交
4009001Invalid settlement amount收款结算金额非法检查金额是否为正数、小数位是否正确
代付（serviceCode = 91）
responseCodemessage触发场景处理建议
4009101Invalid Field Format [{1}]Gateway 校验：时间戳格式错误、orderNo 含特殊字符检查时间戳格式；orderNo 只含字母、数字、下划线、连字符
4009101Invalid request parameter: [{1}]Trade 校验：请求体参数不符合规则根据 {1} 中的字段名修正请求参数
4009101Unsupported area [{1}]请求的地区不在支持范围内确认该地区是否已开通代付服务
4009101Unsupported currency [{1}]请求的币种不在支持范围内确认该地区支持的币种列表
4009101Currency does not match area请求币种与地区不匹配修改币种为该地区支持的币种
4009101Duplicate payout order代付订单号重复先查询该 orderNo 的订单状态
4009101Invalid payout amount代付金额非法检查金额是否为正数、是否在限额范围内
状态查询（serviceCode = 92）
responseCodemessage触发场景处理建议
4009201Invalid Field Format [{1}]Gateway 校验：请求参数格式错误检查请求参数格式
4009201Invalid request parameter: [{1}]Trade 校验：请求体参数不符合规则根据 {1} 中的字段名修正请求参数

必填字段缺失（caseCode = 02）

responseCodemessage服务处理建议
4009002Invalid Mandatory Field [{1}]收款根据 {1} 中的字段名补充缺失的必填项
4009102Invalid Mandatory Field [{1}]代付同上
4009202Invalid Mandatory Field [{1}]查询同上

常见缺失字段：Content-Type、X-TIMESTAMP、X-SIGNATURE、X-PARTNER-ID、Authorization

code = "11" — 目标资源不存在

路由无效（caseCode = 01）

responseCodemessage服务触发场景处理建议
4049001Invalid Routing收款请求的 URL 路径无法匹配到任何服务确认请求路径为 v2.0/transaction/pay-in
4049101Invalid Routing代付请求的 URL 路径无法匹配到任何服务确认请求路径为 v2.0/disbursement/pay-out
4049201Invalid Routing查询请求的 URL 路径无法匹配到任何服务确认请求路径为 v2.0/inquiry-status

商户不存在（caseCode = 02）

responseCodemessage服务触发场景处理建议
4049002Partner ：{商户ID} Not Found收款商户不存在或已禁用① 确认商户 ID 是否正确；② 在后台查询该商户状态
4049102Partner ：{商户ID} Not Found代付商户不存在或已禁用同上
4049202Partner ：{商户ID} Not Found查询商户不存在或已禁用同上

code = "12" — 身份认证失败

涉及安全认证，如客服无法解决需转技术支持。

未授权（caseCode = 00）

responseCodemessage服务触发场景处理建议
4019000Unauthorized. [{1}]收款RSA 签名验证失败、公钥未配置、IP 不在白名单① 确认 RSA 公钥配置；② 确认签名算法（SHA256withRSA）；③ 确认签名串拼接顺序
4019100Unauthorized. [{1}]代付同上同上
4019200Unauthorized. [{1}]查询同上同上

令牌无效（caseCode = 01）

responseCodemessage服务触发场景处理建议
4019001Invalid Token [{1}]收款JWT Token 无效或已过期① 确认 Access Token 是否有效；② 重新获取 Token；③ 确认 Token 放在 Authorization 请求头中
4019101Invalid Token [{1}]代付同上同上
4019201Invalid Token [{1}]查询同上同上

code = "13" — 请求频繁

responseCodemessage服务触发场景处理建议
4299000TOO_MANY_REQUESTS收款请求频率超过限制，或同一订单正在处理中降低请求频率后重试。如果是订单处理中，先查询订单状态
4299100TOO_MANY_REQUESTS代付同上同上
4299200TOO_MANY_REQUESTS查询请求频率超过限制降低请求频率后重试

code = "14" — 交易被禁止

最复杂的一类，必须看 message 具体内容判断。

交易过期（caseCode = 00）

responseCodemessage服务触发场景处理建议
4039000Transaction Expired收款收款订单已超过有效支付时间告知商户订单已过期，需要重新下单

代付和状态查询不涉及交易过期场景。

黑名单拦截（caseCode = 01）

responseCodemessage服务触发场景处理建议
4039001Do Not Honor, [{1}]收款IP 黑名单、邮箱黑名单、账户号黑名单、身份证号黑名单转安全团队处理
4039101Do Not Honor, [{1}]代付同上转安全团队处理
4039201Do Not Honor, [{1}]查询同上转安全团队处理

交易不被允许（caseCode = 02）

收款（serviceCode = 90）
responseCodemessage触发场景处理建议
4039002Transaction Not Permitted.[{1}]风控拒绝(105)、商户状态无效(109)、订单已失败(131)、操作不允许(132)根据 {1} 中的具体信息判断原因
4039002Transaction declined by risk control交易触发风控规则转风控团队审核
4039002Merchant status is invalid商户已被禁用或状态异常在后台检查商户状态
4039002Pay order has failed对已失败的订单执行了操作告知商户该订单已失败
4039002Pay order operation not allowed in current status当前状态下不允许此操作引导商户检查订单状态
代付（serviceCode = 91）
responseCodemessage触发场景处理建议
4039102Transaction Not Permitted.[{1}]风控拒绝(105)、商户状态无效(109)根据 {1} 中的具体信息判断原因
4039102Transaction declined by risk control交易触发风控规则转风控团队审核
4039102Merchant status is invalid商户已被禁用或状态异常在后台检查商户状态
4039102Payout order operation not allowed in current status代付订单当前状态不允许此操作引导商户检查订单状态
状态查询（serviceCode = 92）
responseCodemessage触发场景处理建议
4039202Transaction Not Permitted.[{1}]同上根据 {1} 中的具体信息判断原因

商户黑名单 / IP 白名单（caseCode = 03）

responseCodemessage服务触发场景处理建议
4039003Merchant Blacklisted. {1}收款商户服务器 IP 不在 IP 白名单中① 确认商户服务器 IP 是否变更；② 收集新 IP，转技术支持添加白名单
4039103Merchant Blacklisted. {1}代付同上同上
4039203Merchant Blacklisted. {1}查询同上同上

配置权限不足（caseCode = 04）

收款（serviceCode = 90）
responseCodemessage触发场景处理建议
4039004Insufficient configuration permission. [{1}]收款产品配置不可用(121)、无可用收款通道(122)引导商户登录后台，进入「通道配置」页面，确保至少有一个通道处于「启用」状态
4039004Pay product config unavailable商户未配置收款产品引导商户配置收款产品
4039004No active pay channel已配置的收款通道全部不可用检查通道状态，如维护需告知商户
代付（serviceCode = 91）
responseCodemessage触发场景处理建议
4039104Insufficient configuration permission. [{1}]代付产品配置不可用(141)、无可用代付通道(142)引导商户登录后台，检查代付通道配置
4039104Payout config unavailable商户未配置代付产品引导商户配置代付产品
4039104No active payout channel已配置的代付通道全部不可用检查代付通道状态
状态查询（serviceCode = 92）
responseCodemessage触发场景处理建议
4039204Insufficient configuration permission. [{1}]商户配置不完整引导商户完善配置

code = "16" — 余额不足

responseCodemessage服务触发场景处理建议
4009003Insufficient Balance. [{1}]收款商户账户可用余额不足告知商户账户余额不足，需要先充值
4009103Insufficient Balance. [{1}]代付商户账户可用余额不足，无法冻结代付所需金额告知商户账户余额不足，需要先充值再进行代付
4009203Insufficient Balance. [{1}]查询商户账户可用余额不足告知商户账户余额不足

code = "20" — 外部通道错误

收款（serviceCode = 90）
responseCodemessage触发场景处理建议
5029000External request error: {1}Gateway 调用下游外部接口失败外部通道临时异常，稍后重试。如频繁出现转技术支持
5029000Callback notify failed, [{1}]Trade 侧商户回调 URL 不可达检查商户回调 URL 是否可达
5029000Pay channel timeout or interrupted通道调用超时通道临时异常，稍后重试
5029000Unknown pay status通道返回无法识别的状态转技术支持确认通道返回内容
代付（serviceCode = 91）
responseCodemessage触发场景处理建议
5029100External request error: {1}Gateway 调用下游外部接口失败外部通道临时异常，稍后重试
5029100Callback notify failed, [{1}]Trade 侧商户回调 URL 不可达检查商户回调 URL 是否可达
5029100Payout channel timeout or interrupted代付通道调用超时通道临时异常，稍后重试
5029100Unknown payout status代付通道返回无法识别的状态转技术支持确认通道返回内容
状态查询（serviceCode = 92）
responseCodemessage触发场景处理建议
5029200External request error: {1}Gateway 调用下游外部接口失败外部通道临时异常，稍后重试

code = "99" — 通用错误

系统内部异常，必须记录完整报文并转技术支持。

收款（serviceCode = 90）
responseCodemessage 示例根因处理建议
5009000Payment method: XXX inactive for merchant: XXX商户的支付方式未激活引导商户在后台激活该支付方式
5009000Failed to generate order number订单号生成服务异常系统临时异常，稍后重试
5009000Unable to create pay order创建收款订单失败记录 orderNo/tradeNo 转技术排查
5009000Pay channel error: {1}支付通道返回拒绝转技术支持确认通道状态
5009000Pay order not found代收订单不存在确认 orderNo/tradeNo 是否正确
5009000The requested pay order was not found平台单号对应代收订单不存在确认订单号是否正确
5009000System error: {1}系统通用异常记录完整报文，立即转技术支持
代付（serviceCode = 91）
responseCodemessage 示例根因处理建议
5009100Payment method: XXX inactive for merchant: XXX商户的支付方式未激活引导商户在后台激活该支付方式
5009100Failed to generate order number订单号生成服务异常系统临时异常，稍后重试
5009100Unable to create payout order创建代付订单失败记录 orderNo/tradeNo 转技术排查
5009100Payout channel error: {1}代付通道返回拒绝转技术支持确认通道状态
5009100Payout order not found代付订单不存在确认订单号是否正确
5009100The requested payout order was not found平台单号对应代付订单不存在确认订单号是否正确
5009100The requested withdrawal order was not found提现订单不存在确认提现订单号
5009100System error: {1}系统通用异常记录完整报文，立即转技术支持
状态查询（serviceCode = 92）
responseCodemessage 示例根因处理建议
5009200Order not found订单不存在确认 orderNo/tradeNo 是否正确
5009200System error: {1}系统通用异常记录完整报文，立即转技术支持

快速话术库

参数类（code = 10 / 11）

场景适用 code话术
参数格式错误10「您的请求参数存在格式问题：{具体原因}。请检查后重试。」
必填字段缺失10「您的请求缺少必填字段 {字段名}，请补充后重试。」
订单重复10「订单号 {orderNo} 已处理过，请先查询该订单状态，不要重复提交。」
商户不存在11「商户 ID {merchantId} 不存在或已禁用，请确认后重试。」
路由无效11「请求路径无效，请确认您使用的是正确的 API 地址。收款：v2.0/transaction/pay-in，代付：v2.0/disbursement/pay-out」

认证类（code = 12 / 13）

场景适用 code话术
签名失败12「签名验证失败，请检查：① RSA 公钥配置是否正确；② 签名算法是否为 SHA256withRSA；③ 签名串拼接是否与文档一致。」
Token 无效12「Access Token 已过期或无效，请重新获取 Token 后重试。」
请求频繁13「请求频率过高，请稍后重试。建议控制请求频率。」
订单处理中13「该订单正在处理中，请先查询订单状态，不要重复提交。」

风控与限制类（code = 14 / 16）

场景适用 code话术
交易过期14「订单已过期，请重新下单。」
黑名单拦截14「您的请求被安全策略拦截，我们需要进一步核实。请提供商户 ID 和请求时间。」→ 转安全团队
风控拒绝14「交易被风控系统拒绝，我们需要进一步审核。」→ 转风控团队
IP 白名单14「您的服务器 IP 不在白名单中，请确认 IP 地址或联系技术支持添加。」
配置不足14「您的商户账户尚未配置完整的收款/代付通道，请登录后台配置至少一个可用通道。」
余额不足16「您的商户账户余额不足，请先充值再进行代付操作。」

系统类（code = 20 / 99）

场景适用 code话术
通道异常20「第三方支付通道出现临时异常，请稍后重试。如持续出现我们会及时排查。」→ 转技术支持
系统异常99「系统出现异常，我们已记录相关信息并转交技术团队排查。请稍后重试。」→ 记录完整报文，转技术支持
Copyright © 2026 smilepayz teams