错误码说明
响应状态码
所有接口返回结果中都包含 code 字段，用于表示请求处理结果。成功时为 "0000"，失败时为对应的错误码。
状态码枚举
| 状态码 | 枚举名 | 说明 | 解决方案 |
|---|---|---|---|
| 0000 | SUCCESS | 成功 | - |
| 4001 | PARAM_ERROR | 参数错误 | 检查必填参数是否完整，参数格式是否正确 |
| 4002 | UNAUTHORIZED | 未授权 | 检查认证信息，确认 access_token 或 API 密钥是否有效 |
| 4003 | FORBIDDEN | 禁止访问 | 检查权限配置，确认是否有接口访问权限 |
| 4004 | NOT_FOUND | 资源不存在 | 检查请求的资源 ID 是否正确 |
| 5000 | SYSTEM_ERROR | 系统错误 | 请联系技术支持，提供请求 ID 和时间戳 |
业务错误码
除通用状态码外，业务接口可能返回以下错误码：
| 错误码 | 说明 | 解决方案 |
|---|---|---|
| 1001 | 签名验证失败 | 检查签名算法是否正确，密钥是否匹配 |
| 1002 | 用户不存在 | 检查 userId 是否正确 |
| 1003 | 应用不存在 | 检查 appId 是否正确 |
| 2001 | 余额不足 | 检查账户余额 |
| 2002 | 超过限额 | 检查交易金额是否超过限制 |
| 3001 | 订单不存在 | 检查订单号是否正确 |
| 3002 | 订单状态异常 | 订单已处理或已关闭 |
错误响应示例
{
"code": "4001",
"message": "参数错误：缺少必填字段'appId'",
"timestamp": "2026-07-01T10:30:00.000Z",
"data": {}
}
错误处理建议
- 参数错误（4001）：仔细核对请求参数，确保必填字段完整且格式正确
- 未授权（4002）：检查 access_token 是否过期，重新获取认证
- 禁止访问（4003）：确认应用权限配置，联系管理员开通接口权限
- 资源不存在（4004）：检查请求的订单号、商户 ID 等资源标识
- 系统错误（5000）：建议实现重试机制，间隔 1-3 秒后重试，若持续失败请联系技术支持