错误码
错误码体系
DaxPay 有两层 API，响应结构略有不同：
支付 API（/unipay/*）— DaxResult：
{
"code": 0,
"msg": "success",
"data": { }
}管理 API（/mch/*）— Result：
{
"code": 0,
"message": "success",
"data": { }
}| 字段 | 类型 | 支付 API | 管理 API | 说明 |
|---|---|---|---|---|
code | int | ✓ | ✓ | 业务状态码。0 表示成功,非 0 表示失败 |
msg | string | ✓ | — | 提示信息（DaxResult 字段名） |
message | string | — | ✓ | 已按 Accept-Language 翻译的可读文案（Result 字段名） |
data | object|null | ✓ | ✓ | 业务数据,失败时通常为 null |
sign | string | ✓ | — | RSA 响应签名（仅支付 API） |
resTime | string | ✓ | — | 响应时间 UTC（仅支付 API） |
reqId | string | ✓ | — | 请求 ID 回显（仅支付 API） |
- 成功:
{"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 | 未授权(Accesstoken 缺失或无效) |
| 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 | 未知异常,系统无法处理 |
用户中心错误码 IamErrorCode(21000-21999)
主要出现在管理端 / 商户端的登录、用户、角色、权限场景。
| 状态码 | 常量 | 含义 |
|---|---|---|
21014 | USER_EMAIL_ALREADY_EXISTED | 用户 Email 已存在 |
21015 | USER_PHONE_ALREADY_EXISTED | 用户手机号已存在 |
21020 | USER_INFO_NOT_EXISTS | 用户信息不存在 |
21022 | DUPLICATE_PHONE_NUMBER | 手机号重复(批量导入) |
21023 | DUPLICATE_EMAIL_ADDRESS | 邮箱重复(批量导入) |
21024 | NONE_PHONE_AND_EMAIL | 邮箱和手机号均为空 |
21025 | ROLE_ALREADY_EXISTED | 角色已存在 |
21026 | ROLE_NOT_EXISTED | 角色不存在 |
21027 | ROLE_ALREADY_USED | 角色已被使用 |
21028 | ROLE_HAS_CHILD / PERMISSION_DB_ERROR | 含有下级角色 / 权限操作错误 |
21029 | PERMISSION_NOT_EXIST | 没有访问权限 |
22016 | USER_PASSWORD_INVALID | 密码不正确 |
业务异常机制
后端业务异常通过 BizInfoException 抛出,构造时同时传入数字 code(决定响应 code 字段)与 messageKey(决定 message 文案):
// 指定 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.error.methodNotExist | 不存在的支付方式 |
error.common.payStatusNotExist | 支付状态不存在 |
error.common.tradeStatusNotExist | 交易状态不存在 |
error.common.payRefundStatusNotExist | 退款状态不存在 |
error.common.normalOrderStatusNotExist | 订单状态不存在 |
字段校验错误
支付通道相关的参数校验遵循以下 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)。