错误码

更新时间：2026/9/16 11:08:10

错误码体系

DaxPay 开放支付 API（/unipay/*）的响应结构为 DaxResult：

json

{
  "code": 0,
  "msg": "success",
  "data": { }
}

字段	类型	说明
`code`	`int`	业务状态码。`0` 表示成功,非 `0` 表示失败
`msg`	`string`	提示信息（已按 `Accept-Language` 翻译的可读文案）
`data`	`object\|null`	业务数据,失败时通常为 `null`
`sign`	`string`	RSA 响应签名
`resTime`	`string`	响应时间（北京时间）
`reqId`	`string`	请求 ID 回显

成功: {"code": 0, "msg": "success", ...}
失败: {"code": 10506, "msg": "通道路由未找到匹配通道", "data": null}

错误文案支持 10 语种国际化(zh-CN / en-US / zh-TW / zh-HK / ja-JP / ko-KR / id-ID / vi-VN / th-TH / ms-MY),由请求头 Accept-Language 决定返回语言。code 是数字分类码,与文案独立 —— 同一文案可能用不同 code 抛出,定位问题时以 code 为准。

HTTP 状态码对照

HTTP 状态码	说明
200	请求成功,具体业务结果见响应体 `code`
400	请求参数格式错误
401	未授权（认证失败）
403	禁止访问(权限不足)
404	接口不存在
429	请求频率超限
500	服务器内部错误

错误码字典

错误码由后端常量类定义,按业务域分段。以下取自开源版真实源码:

基础码 CommonCode

状态码	常量	含义
`0`	`SUCCESS_CODE`	成功
`1`	`FAIL_CODE`	失败(未细分类的通用失败兜底码)

通用错误码 CommonErrorCode(10000-19999)

状态码	常量	含义
`10401`	`AUTHENTICATION_FAIL`	认证失败(Token 过期 / 无效)
`10404`	`SOURCES_NOT_EXIST`	资源不存在
`10405`	`DATA_NOT_EXIST`	数据不存在
`10408`	`NONCE_MISSING`	Nonce 缺失
`10409`	`NONCE_INVALID`	Nonce 无效或已过期
`10410`	`TIMESTAMP_EXPIRED`	请求时间戳超出允许范围
`10415`	`UN_SUPPORTED_OPERATE`	不支持的操作
`10500`	`SYSTEM_ERROR`	系统错误
`10505`	`PARSE_PARAMETERS_ERROR`	参数解析失败
`10506`	`VALIDATE_PARAMETERS_ERROR`	参数校验失败
`10507`	`REPETITIVE_OPERATION_ERROR`	重复操作
`10512`	`DANGER_SQL`	危险 SQL 异常

支付错误码 PayErrorCode(20000-29999)

状态码	常量	含义
`20000`	`UNCLASSIFIED_ERROR`	未归类的支付错误
`20011`	`CHANNEL_NOT_EXIST`	支付通道不存在
`20012`	`METHOD_NOT_EXIST`	支付方式不存在
`20013`	`STATUS_NOT_EXIST`	支付状态不存在
`20021`	`CHANNEL_NOT_ENABLE`	支付通道未启用
`20022`	`METHOD_NOT_ENABLE`	支付方式未启用
`20023`	`CONFIG_NOT_ENABLE`	配置未启用
`20024`	`CONFIG_ERROR`	配置错误
`20025`	`CONFIG_NOT_EXIST`	配置不存在
`20030`	`UNSUPPORTED_ABILITY`	不支持该支付能力
`20041`	`TRADE_NOT_EXIST`	交易不存在
`20042`	`TRADE_CLOSED`	交易已关闭
`20043`	`TRADE_PROCESSING`	交易处理中,请勿重复操作
`20044`	`TRADE_STATUS_ERROR`	交易状态错误
`20045`	`TRADE_FAIL`	交易失败
`20052`	`VERIFY_SIGN_FAILED`	验签失败
`20060`	`AMOUNT_EXCEED_LIMIT`	金额超过限额
`20080`	`OPERATION_FAIL`	操作失败
`20081`	`OPERATION_PROCESSING`	操作处理中,请勿重复操作
`20082`	`OPERATION_UNSUPPORTED`	不支持的操作
`20091`	`DATA_ERROR`	数据错误

系统未知错误（越界码）

30000 不在 20000-29999 段内

SYSTEM_UNKNOWN_ERROR 虽定义在 PayErrorCode 类中,但其 code 值 30000 已超出该类的 20000-29999 段,作为「未知异常」单独存在。对接时遇到此码表示发生了未预期的系统级异常,需联系平台排查。

状态码	常量	含义
`30000`	`SYSTEM_UNKNOWN_ERROR`	未知异常,系统无法处理

业务异常机制

后端业务异常通过 BizInfoException 抛出,构造时同时传入数字 code(决定响应 code 字段)与 messageKey(决定 message 文案):

java

// 指定 code + messageKey
throw new BizInfoException(PayErrorCode.TRADE_STATUS_ERROR, "pay.order.status.invalid");
// 仅 messageKey,code 取默认 FAIL_CODE = 1
throw new BizInfoException("pay.route.error.noMatch");

code 来自上述常量类,决定错误分类
messageKey 对应 i18n/{locale}/ 下资源文件中的文案 key,决定 message 显示内容

code 与 messageKey 的关系

二者独立:同一 messageKey 可被不同 code 抛出(如 pay.route.error.noMatch 多处用 VALIDATE_PARAMETERS_ERROR=10506 抛出,也可能用 FAIL_CODE=1)。对接排错时以响应体的 code 定位错误分类,以 message 理解具体原因。

常见 messageKey 文案

完整 messageKey 字典见后端 daxpay-platform-common/common-i18n/src/main/resources/i18n/{locale}/(按业务模块分文件组织,共数百条)。下表列出对接高频项:

messageKey	含义
`pay.route.error.noMatch`	通道路由无匹配
`pay.route.error.channelMchEnvMismatch`	通道商户与产品当前生效环境不一致
`pay.error.methodNotExist`	不存在的支付方式
`error.common.payStatusNotExist`	支付状态不存在
`error.common.tradeStatusNotExist`	交易状态不存在
`error.common.payRefundStatusNotExist`	退款状态不存在
`error.common.normalOrderStatusNotExist`	订单状态不存在
`error.channel.allocReceiverDuplicate`	分账接收方已存在（同通道商户同类型同账号）
`error.channel.allocReceiverAlreadyBound`	已绑定的接收方无需重复绑定
`error.channel.allocReceiverNotBound`	仅已绑定的接收方可解绑
`error.channel.allocReceiverBoundCannotDelete`	已绑定的接收方不可删除，请先解绑
`error.channel.allocReceiverCustomRelationRequired`	自定义关系类型必须填写自定义关系名
`error.channel.alipay.transferFailed`	支付宝转账失败:
`error.channel.alipay.allocFailed`	支付宝分账失败:
`error.channel.alipay.allocReceiverBindFailed`	支付宝分账接收方绑定失败:
`error.channel.wechat.transferFailed`	微信转账异常:
`error.channel.wechat.allocReceiverUnsupportedType`	微信: 不支持的分账接收方类型:
`error.channel.douyin.transferFailed`	抖音转账失败:
`error.channel.douyin.transferSceneNotConfigured`	抖音: 转账场景未配置

上表为对接高频词条；分账 / 转账完整词条（支付宝、微信、抖音三通道，共数十条）见后端 common-i18n/.../i18n/{locale}/error/channel/ 下 alipay.json / wechat.json / douyin.json 与 channel.json，不在此穷举。

字段校验错误

支付通道相关的参数校验遵循以下 messageKey 命名规则:

validation.field.{字段名}.{约束}

例如 validation.field.bizOrderNo.notBlank 表示「业务订单号不能为空」。

对应 i18n 文件位置(各语种结构相同,仅 {locale} 目录不同):

简体中文: i18n/zh-CN/validation/field.json
英文: i18n/en-US/validation/field.json
繁体中文 / 日 / 韩 / 东盟四语同结构,位于对应 {locale} 目录下

字段校验失败时,响应 code 为 CommonErrorCode.VALIDATE_PARAMETERS_ERROR(10506)。

错误码 ​

错误码体系 ​

HTTP 状态码对照 ​

错误码字典 ​

基础码 CommonCode ​

通用错误码 CommonErrorCode(10000-19999) ​

支付错误码 PayErrorCode(20000-29999) ​

系统未知错误（越界码） ​

业务异常机制 ​

常见 messageKey 文案 ​

字段校验错误 ​

错误码