错误响应代码

错误代码概述

错误代码系统为API操作提供标准化的响应代码，使开发人员能够适当地处理不同场景。这个综合错误处理系统确保支付平台和客户端应用程序之间的一致通信。

标准响应代码

代码	消息	描述
00	请求成功	您的请求已成功处理 用途：交易完成、操作成功 操作：继续正常业务逻辑
01	请求处理中	请求正在处理中 用途：异步操作、待处理交易 操作：等待完成或稍后检查状态
10	错误请求	无效的请求参数或格式 用途：缺少必需字段、无效数据格式 操作：审查并更正请求参数
11	未找到	请求的资源或端点未找到 用途：无效API端点、不存在的交易 操作：验证API URL和资源标识符
12	未授权	认证或授权失败 用途：无效凭据、权限不足 操作：检查认证配置
13	请求过多	超出速率限制 用途：API调用频率超过允许限制 操作：实施速率限制并使用退避重试
14	禁止访问	由于业务规则拒绝访问 用途：账户限制、支付方式限制 操作：联系业务发展团队
15	超时	请求处理超时 用途：网络问题、系统过载 操作：检查网络连接并重试
16	余额不足	账户余额不足以进行交易 用途：付款或提现资金不足 操作：检查账户余额并添加资金
99	一般错误	系统或渠道错误 用途：意外系统错误、第三方服务问题 操作：联系技术支持

错误处理最佳实践

成功场景（代码00）

• 响应: 交易成功完成
• 操作: 更新本地记录，通知用户成功
• 日志: 记录成功交易以供审计

处理中场景（代码01）

• 响应: 请求正在处理中
• 操作: 实施轮询机制检查状态
• 超时: 为状态检查设置适当的超时

客户端错误场景（代码10-16）

• 代码10 - 错误请求:

  • 验证所有必需参数是否存在
  • 检查参数格式和数据类型
  • 根据API文档验证请求结构

• 代码11 - 未找到:

  • 验证API端点URL是否正确
  • 检查资源标识符（orderNo、tradeNo等）
  • 确保API版本兼容性

• 代码12 - 未授权:

  • 验证签名生成和验证
  • 检查商户凭据和权限
  • 确保支付方式配置正确
  • 参考：签名生成指南

• 代码13 - 请求过多:

  • 实施指数退避策略
  • 减少API调用频率
  • 监控速率限制头部（如果可用）

• 代码14 - 禁止访问:

  • 联系业务发展团队
  • 验证账户状态和权限
  • 检查支付方式激活状态

• 代码15 - 超时:

  • 检查网络连接
  • 验证服务器可用性
  • 实施具有递增延迟的重试机制

• 代码16 - 余额不足:

  • 交易前检查账户余额
  • 在应用程序逻辑中实施余额验证
  • 提供关于资金不足的清晰用户反馈

系统错误场景（代码99）

• 响应: 一般系统或渠道错误
• 操作: 联系技术支持并提供详细的错误信息
• 日志: 记录完整的错误详情以供故障排除
• 重试: 为临时错误实施智能重试机制

实施指南

错误响应结构

{
  "code": "10",
  "message": "错误请求",
  "details": "缺少必需参数: merchantId",
  "timestamp": "2020-12-17T10:55:00-05:00",
  "requestId": "req_123456789"
}

错误处理策略

1. 立即操作: 根据响应代码处理错误
2. 用户通信: 提供清晰、可操作的错误消息
3. 日志: 记录所有错误，包含足够的调试详情
4. 重试逻辑: 为临时错误实施适当的重试策略