第16章：错误码索引

本文档提供 WMS API 所有错误码的快速索引，便于快速查找错误码含义和解决方案。

15.1 错误码分类

15.1.1 系统级错误码

注意：错误码列表将持续更新，如遇到未列出的错误码，请查看 errorMsg 字段获取详细错误信息，或联系技术支持。

15.2 错误码详细说明

15.2.1 401 用户认证失败

错误码：401

HTTP Code：401

是否可重试：❌ 否

错误描述：用户认证失败

可能原因：

1. Token 无效或已过期

2. Token 格式错误

3. 请求头中缺少 Authorization 字段

4. Authorization 字段格式错误

解决方案：

1. 重新调用 Token 获取接口获取新的 Token

2. 检查请求头格式：Authorization: Bearer {token}

3. 确认 Token 未过期（有效期为 24 小时）

4. 检查 API Key 和 API Secret 是否正确

15.2.2 403 权限不足

错误码：403

HTTP Code：403

是否可重试：❌ 否

错误描述：权限不足

可能原因：

1. 账号没有访问该接口的权限

2. API Key 对应的账号权限受限

解决方案：

1. 联系管理员确认账号权限

2. 确认 API Key 是否有访问该接口的权限

3. 检查是否需要申请额外权限

15.2.3 405 验证码校验失败

错误码：405

HTTP Code：405

是否可重试：❌ 否

错误描述：验证码校验失败

可能原因：

1. 验证码错误

2. 验证码已过期

3. 验证码格式错误

解决方案：

1. 重新输入验证码

2. 确认验证码未过期

3. 检查验证码格式是否正确

15.2.4 500 服务器错误

错误码：500

HTTP Code：200

是否可重试：✅ 是

错误描述：服务器错误

可能原因：

1. 后端服务异常

2. 数据库连接异常

3. 第三方服务异常

解决方案：

1. 可以重试：这是唯一可以重试的错误码

2. 实现指数退避重试策略（1秒、2秒、4秒）

3. 最多重试 3 次

4. 如果重试后仍然失败，联系技术支持

重试策略：

• 第1次重试：等待 1 秒
• 第2次重试：等待 2 秒
• 第3次重试：等待 4 秒

15.2.5 1000 无效的参数

错误码：1000

HTTP Code：200

是否可重试：❌ 否

错误描述：无效的参数

可能原因：

1. 必填参数为空

2. 参数格式不符合要求

3. 参数值超出允许范围

4. 参数类型错误

解决方案：

1. 检查请求参数是否完整

2. 检查参数格式是否正确（日期格式、字符串格式等）

3. 检查参数值是否在允许范围内

4. 查看 errorMsg 字段获取详细错误信息

5. 参考接口文档中的参数说明

15.2.6 1006 不支持的请求参数

错误码：1006

HTTP Code：200

是否可重试：❌ 否

错误描述：不支持的请求参数

可能原因：

1. 请求参数格式错误

2. 参数值类型不匹配

3. JSON 格式错误

解决方案：

1. 检查请求参数的 JSON 格式

2. 检查参数值类型是否正确

3. 参考接口文档中的请求示例

15.2.7 1007 不支持的请求类型

错误码：1007

HTTP Code：200

是否可重试：❌ 否

错误描述：不支持的请求类型

可能原因：

1. HTTP 方法错误（如：应该用 POST 却用了 GET）

2. 接口不支持该 HTTP 方法

解决方案：

1. 检查请求方法是否正确（GET/POST/PUT/DELETE）

2. 参考接口文档中的请求方式说明

15.2.8 1012 第三方初始化失败

错误码：1012

HTTP Code：200

是否可重试：❌ 否

错误描述：第三方初始化失败

可能原因：

1. 第三方服务初始化异常

2. 第三方服务配置错误

解决方案：

1. 联系技术支持

2. 提供错误详情和请求信息

15.2.9 2003 当前的数据不支持此操作

错误码：2003

HTTP Code：200

是否可重试：❌ 否

错误描述：当前的数据不支持此操作

可能原因：

1. 数据状态不允许当前操作

2. 订单状态不符合操作要求（如：只能更新 Pending 或 Special 状态的订单）

解决方案：

1. 检查数据状态

2. 查看接口文档中的状态要求

3. 确认操作是否符合业务规则

示例：

• 只能更新 Pending 或 Special 状态的出库订单
• 只能取消特定状态的订单（Hold 和 Cancelled 状态不支持取消；Fulfiled 状态且 Tracking Status 不为 Label Created 时也不支持取消）
• 仅 Working 和 Fulfiled 状态的订单支持 Hold 操作
• 仅支持 Pending 和 Special 状态的订单删除

15.3 错误处理流程

收到错误响应
    ↓
检查 errorCode
    ↓
┌─────────────────┐
│ errorCode == 500│
└─────────────────┘
    ↓ 是
实现重试逻辑（指数退避，最多3次）
    ↓
┌─────────────────┐
│ 其他错误码      │
└─────────────────┘
    ↓ 否
根据错误码类型处理：
- 401: 重新获取 Token
- 403: 联系管理员
- 1000: 检查并修正参数
- 其他: 查看 errorMsg，联系技术支持

15.4 快速查找

15.4.1 按错误类型查找

• 认证相关：401
• 权限相关：403
• 参数相关：1000, 1006, 1007
• 业务逻辑相关：2003
• 系统错误：500, 1012

15.4.2 按是否可重试查找

• 可重试：500
• 不可重试：401, 403, 405, 1000, 1006, 1007, 1012, 2003

反馈与建议

如有任何问题或建议，请联系技术支持团队。