错误码文档

文档说明

本文档整理了错误码，包括错误码定义、HTTP状态码、使用场景和触发条件。

1. 错误码定义总览

1.1 成功码

错误码	消息	HTTP状态码	说明
SUCCESS	成功	200	请求处理成功

1.2 通用错误码 (1000-1999)

错误码	消息	HTTP状态码	说明
ERROR	系统错误	500	通用系统错误
PARAM_ERROR	参数错误	400	请求参数错误或缺失
VALIDATION_ERROR	参数验证失败	400	参数格式或内容验证失败
UNAUTHORIZED	未授权	401	未授权访问
FORBIDDEN	禁止访问	403	无权限访问资源
NOT_FOUND	资源不存在	404	请求的资源不存在
CONFLICT	资源冲突	409	资源冲突（如重复请求）
RATE_LIMIT_EXCEEDED	请求频率超限	429	超过接口访问频率限制
INTERNAL_ERROR	系统内部错误	500	系统内部异常

1.3 签名相关错误码 (2000-2099)

错误码	消息	HTTP状态码	说明
SIGNATURE_MISSING	缺少签名信息	401	请求头缺少必要的签名参数
SIGNATURE_INVALID	签名验证失败	401	签名不正确或已失效
TIMESTAMP_INVALID	时间戳无效或已过期	401	请求时间戳超出允许范围
NONCE_DUPLICATE	随机数重复	401	检测到重复的nonce值
IP_NOT_ALLOWED	IP地址不允许访问	403	客户端IP不在白名单中

1.4 商户相关错误码 (3000-3099)

错误码	消息	HTTP状态码	说明
MERCHANT_NOT_FOUND	商户不存在	404	商户ID对应的配置不存在
MERCHANT_DISABLED	商户已被禁用	403	商户账户已被停用
MERCHANT_NOT_AUTHORIZED	商户无权限访问	403	商户无权访问该资源或接口
SUB_MCHID_NOT_MATCH	特约商户号与商户绑定关系不匹配	400	特约商户号与系统记录不一致

1.5 批量转账相关错误码 (4000-4099)

错误码	消息	HTTP状态码	说明
BATCH_NO_EXISTS	商家批次单号已存在	409	批次单号重复
BATCH_NO_NOT_FOUND	商家批次单号不存在	404	查询的批次单不存在
DETAIL_NO_EXISTS	商家明细单号已存在	409	批次明细单号重复
BATCH_PROCESSING	批次正在处理中，请勿重复提交	409	批次正在处理，不可重复提交
BATCH_STATUS_INVALID	批次状态无效	400	批次状态不符合预期

1.6 微信支付相关错误码 (5000-5099)

错误码	消息	HTTP状态码	说明
WECHAT_PAY_ERROR	微信支付服务错误	500	微信支付接口返回错误
WECHAT_PAY_NETWORK_ERROR	微信支付网络请求失败	500	调用微信支付接口网络异常
WECHAT_PAY_SIGNATURE_ERROR	微信支付签名验证失败	401	微信支付回调签名验证失败
WECHAT_PAY_SERVICE_ERROR	微信支付服务异常	500	微信支付服务端异常
WECHAT_PAY_PARAM_ERROR	微信支付参数错误	400	传递给微信支付的参数错误
WECHAT_PAY_ACCOUNT_ERROR	商户账户错误	400	微信支付商户账户配置错误
WECHAT_PAY_NOT_ENOUGH	商户账户资金不足	400	商户余额不足以完成转账
WECHAT_PAY_QUOTA_EXCEED	超出商户单日转账额度	400	超过微信支付转账额度限制
WECHAT_PAY_FREQUENCY_LIMITED	请求频率超限	429	超过微信支付接口频率限制

2. 签名错误码使用

2.1 签名错误码

错误码使用:

场景	错误码	HTTP状态码	触发条件
IP不在白名单	IP_NOT_ALLOWED	403	客户端IP不在AppConfig或全局IP白名单中
重复请求	CONFLICT	409	相同请求在30秒内重复提交
签名验证失败	SIGNATURE_INVALID	401	签名不正确、时间戳过期、缺少签名参数等

请求头要求:

X-Timestamp: 请求时间戳（毫秒，13位）

X-Nonce: 随机数（≤128位，只能使用一次）

X-Signature: 请求签名（HMAC-SHA256，小写16进制）

X-Client-Id: 客户/应用ID（推荐，兼容旧版 X-App-Id）

X-Biz-Merchant-Id: 业务方商户ID（推荐，兼容旧版 X-Merchant-Id）

📖 详细签名规则请参考签名生成详细规则

2.2 限流错误码

错误码使用:

场景	HTTP状态码	触发条件
超过限流阈值	429	在时间窗口内请求次数超过注解配置的limit值

响应格式:

{
  "code": 429,
  "message": "限流消息",
  "success": false
}

3. 接口错误码使用详情

3.1 批量转账接口

3.1.1 POST `/api/v1/partner-transfer/batch/create` - 创建批量转账

限流: 每商户每秒5次

可能返回的错误码:

错误码	场景	说明
RATE_LIMIT_EXCEEDED	超过限流	每商户每秒最多5次请求
BATCH_PROCESSING	批次处理中	相同批次号正在处理
MERCHANT_NOT_AUTHORIZED	商户无权限	商户配置验证失败
VALIDATION_ERROR	参数验证失败	请求参数不符合规范
BATCH_NO_EXISTS	批次号重复	商家批次单号已存在
DETAIL_NO_EXISTS	明细号重复	商家明细单号已存在
WECHAT_PAY_*	微信支付错误	微信支付接口返回的各类错误
ERROR	系统异常	未预期的系统错误

3.1.2 GET `/api/v1/partner-transfer/batch/status` - 查询批次状态

限流: 每商户每秒50次

可能返回的错误码:

错误码	场景
RATE_LIMIT_EXCEEDED	超过限流
MERCHANT_NOT_FOUND	商户配置不存在
BATCH_NO_NOT_FOUND	批次单号不存在
ERROR	查询异常

3.1.3 GET `/api/v1/partner-transfer/batch/details` - 查询批次明细

限流: 每商户每秒50次

可能返回的错误码:

错误码	场景
RATE_LIMIT_EXCEEDED	超过限流
MERCHANT_NOT_FOUND	商户配置不存在
BATCH_NO_NOT_FOUND	批次单号不存在
ERROR	查询异常

4. 全局异常错误码

异常类型	错误码	HTTP状态码	说明
Exception	INTERNAL_ERROR	500	所有未捕获异常
NullPointerException	PARAM_ERROR	400	空指针异常
IllegalArgumentException	PARAM_ERROR	400	非法参数异常
MethodArgumentNotValidException	VALIDATION_ERROR	400	参数验证失败
BindException	VALIDATION_ERROR	400	参数绑定失败
ConstraintViolationException	VALIDATION_ERROR	400	约束验证失败

5. 响应格式规范

5.1 成功响应格式

{
  "success": true,
  "code": "SUCCESS",
  "message": "成功",
  "data": {
    // 业务数据
  }
}

5.2 错误响应格式

{
  "success": false,
  "code": "ERROR_CODE",
  "message": "错误描述信息",
  "data": null
}

5.3 限流响应格式

{
  "code": 429,
  "message": "频率限制，请稍后再试",
  "success": false
}

响应头（限流时）:

X-RateLimit-Limit: 限流阈值

X-RateLimit-Remaining: 剩余请求次数

X-RateLimit-Reset: 限流重置时间戳

6. 错误码使用最佳实践

6.1 客户端处理建议

根据HTTP状态码判断错误类型:

400: 客户端参数错误，检查请求参数

401: 认证失败，检查签名和时间戳

403: 权限不足，检查商户权限和IP白名单

404: 资源不存在

409: 资源冲突，避免重复提交

429: 请求过于频繁，实施退避重试

500: 服务器错误，稍后重试

根据错误码实施重试策略:

RATE_LIMIT_EXCEEDED, WECHAT_PAY_FREQUENCY_LIMITED: 指数退避重试

INTERNAL_ERROR, WECHAT_PAY_SERVICE_ERROR: 延迟重试

VALIDATION_ERROR, PARAM_ERROR: 不应重试，修正参数

SIGNATURE_INVALID, IP_NOT_ALLOWED: 不应重试，检查配置

错误码分组处理:

2000-2099 签名类错误: 检查签名配置和时间同步

3000-3099 商户类错误: 联系管理员检查商户配置

4000-4099 业务类错误: 检查业务参数和状态

5000-5099 微信支付错误: 参考微信支付文档

7. 常见问题排查

7.1 签名验证失败

错误码: SIGNATURE_INVALID

可能原因:

签名算法不正确

时间戳过期（允许偏差±5分钟）

请求参数顺序错误

密钥配置错误

请求体编码问题

排查步骤:

检查日志中的详细错误信息

验证客户端和服务器时间同步

确认签名算法和密钥配置

使用工具验证签名字符串

7.2 IP白名单限制

错误码: IP_NOT_ALLOWED

可能原因:

客户端IP未配置在白名单

使用了代理，获取到的IP不正确

排查步骤:

确认网络代理配置正确

7.3 批量转账失败

错误码: BATCH_NO_EXISTS, WECHAT_PAY_*

可能原因:

批次号重复

商户配置不正确

微信支付账户问题

参数格式错误

排查步骤:

检查批次号唯一性

验证商户配置完整性

查看微信支付商户平台

参考批量转账日志

8. 版本历史

版本	日期	说明
1.0	2025-11-11	初始版本，整理所有错误码

9. 联系方式

如有疑问或发现文档问题，请联系开发团队。

特别说明（新版请求头：新优先，旧兼容）

本页面示例头部为旧版命名（X-App-Id / X-Merchant-Id），平台现已支持：

优先使用：X-Client-Id、X-Biz-Merchant-Id

兼容旧版：X-App-Id、X-Merchant-Id

文档说明#

1. 错误码定义总览#

1.1 成功码#

1.2 通用错误码 (1000-1999)#

1.3 签名相关错误码 (2000-2099)#

1.4 商户相关错误码 (3000-3099)#

1.5 批量转账相关错误码 (4000-4099)#

1.6 微信支付相关错误码 (5000-5099)#

2. 签名错误码使用#

2.1 签名错误码#

2.2 限流错误码#

3. 接口错误码使用详情#

3.1 批量转账接口#

3.1.1 POST /api/v1/partner-transfer/batch/create - 创建批量转账#

3.1.2 GET /api/v1/partner-transfer/batch/status - 查询批次状态#

3.1.3 GET /api/v1/partner-transfer/batch/details - 查询批次明细#

4. 全局异常错误码#

5. 响应格式规范#

5.1 成功响应格式#

5.2 错误响应格式#

5.3 限流响应格式#

6. 错误码使用最佳实践#

6.1 客户端处理建议#

7. 常见问题排查#

7.1 签名验证失败#

7.2 IP白名单限制#

7.3 批量转账失败#

8. 版本历史#

9. 联系方式#

特别说明（新版请求头：新优先，旧兼容）#

文档说明

1. 错误码定义总览

1.1 成功码

1.2 通用错误码 (1000-1999)

1.3 签名相关错误码 (2000-2099)

1.4 商户相关错误码 (3000-3099)

1.5 批量转账相关错误码 (4000-4099)

1.6 微信支付相关错误码 (5000-5099)

2. 签名错误码使用

2.1 签名错误码

2.2 限流错误码

3. 接口错误码使用详情

3.1 批量转账接口

3.1.1 POST `/api/v1/partner-transfer/batch/create` - 创建批量转账

3.1.2 GET `/api/v1/partner-transfer/batch/status` - 查询批次状态

3.1.3 GET `/api/v1/partner-transfer/batch/details` - 查询批次明细

4. 全局异常错误码

5. 响应格式规范

5.1 成功响应格式

5.2 错误响应格式

5.3 限流响应格式

6. 错误码使用最佳实践

6.1 客户端处理建议

7. 常见问题排查

7.1 签名验证失败

7.2 IP白名单限制

7.3 批量转账失败

8. 版本历史

9. 联系方式

特别说明（新版请求头：新优先，旧兼容）