# 设备模块错误码文档

本文档详细列出设备交互模块可能返回的错误码、错误描述及处理建议。

## 错误响应格式

所有API错误响应均遵循以下格式：

```json
{
  "status": "error",
  "message": "错误描述信息",
  "code": "ERROR_CODE"
}
```

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

| 错误码 | 描述 | 处理建议 |
|--------|------|----------|
| 1001 | 参数错误 | 检查请求参数是否完整且格式正确 |
| 1002 | 权限不足 | 确认用户是否已登录且具有相应权限 |
| 1003 | 资源不存在 | 检查请求的资源ID是否正确 |
| 1004 | 操作被拒绝 | 当前状态下不允许此操作 |
| 1005 | 系统内部错误 | 请联系系统管理员 |
| 1006 | 请求超时 | 请稍后重试 |
| 1007 | 并发请求过多 | 降低请求频率 |
| 1008 | 数据库操作失败 | 请联系系统管理员 |
| 1009 | 配置错误 | 请联系系统管理员 |

## 设备类型错误码 (2000-2099)

| 错误码 | 描述 | 处理建议 |
|--------|------|----------|
| 2001 | 设备类型不存在 | 检查设备类型ID是否正确 |
| 2002 | 设备类型代码已存在 | 更换一个新的设备类型代码 |
| 2003 | 设备类型名称已存在 | 更换一个新的设备类型名称 |
| 2004 | 设备类型不可删除 | 该设备类型已关联设备，不可删除 |
| 2005 | 设备类型字段验证失败 | 检查字段格式是否正确 |

## 设备批次错误码 (2100-2199)

| 错误码 | 描述 | 处理建议 |
|--------|------|----------|
| 2101 | 设备批次不存在 | 检查设备批次ID是否正确 |
| 2102 | 批次编号已存在 | 更换一个新的批次编号 |
| 2103 | 生产日期格式错误 | 确保日期格式为YYYY-MM-DD |
| 2104 | 批次不可删除 | 该批次已关联设备，不可删除 |
| 2105 | 设备数量超出限制 | 批次设备数量不能超过系统设定的最大值 |
| 2106 | 批次字段验证失败 | 检查字段格式是否正确 |

## 设备错误码 (2200-2299)

| 错误码 | 描述 | 处理建议 |
|--------|------|----------|
| 2201 | 设备不存在 | 检查设备ID是否正确 |
| 2202 | 设备码已存在 | 确保设备码唯一 |
| 2203 | 序列号已存在 | 在同一批次中序列号必须唯一 |
| 2204 | MAC地址格式错误 | MAC地址格式应为XX:XX:XX:XX:XX:XX |
| 2205 | MAC地址已存在 | MAC地址必须唯一 |
| 2206 | 设备已激活 | 已激活设备不可修改某些字段 |
| 2207 | 设备未激活 | 设备需要先激活才能执行此操作 |
| 2208 | 批量创建参数错误 | 检查批量创建的参数是否正确 |
| 2209 | 批量创建MAC地址冲突 | 生成的MAC地址存在冲突，尝试更换MAC前缀 |
| 2210 | 批量创建序列号冲突 | 生成的序列号存在冲突，尝试更换起始序列号 |
| 2211 | 设备已经绑定 | 设备已经绑定给其他用户 |
| 2212 | 设备不可删除 | 已激活或已绑定的设备不可删除 |

## 用户设备关联错误码 (2300-2399)

| 错误码 | 描述 | 处理建议 |
|--------|------|----------|
| 2301 | 用户设备关联不存在 | 检查用户设备关联ID是否正确 |
| 2302 | 设备已被绑定 | 该设备已被其他用户绑定 |
| 2303 | 设备绑定超过限制 | 用户绑定设备数量已达到上限 |
| 2304 | 设备未绑定 | 设备需要先绑定才能执行此操作 |
| 2305 | 无法设置为主要设备 | 检查设备是否可以设置为主要设备 |
| 2306 | 设备类型不支持设置为主要设备 | 该设备类型不支持设置为主要设备 |
| 2307 | 解绑间隔时间不足 | 两次解绑操作间隔时间不足，请稍后再试 |
| 2308 | 无权操作此设备 | 用户只能操作自己绑定的设备 |

## 火山引擎Token错误码 (2400-2499)

| 错误码 | 描述 | 处理建议 |
|--------|------|----------|
| 2401 | 火山引擎配置错误 | 系统火山引擎配置有误，请联系管理员 |
| 2402 | Token生成失败 | 火山引擎服务异常，请稍后重试 |
| 2403 | 无效的过期时间 | 过期时间必须大于0且小于系统最大限制 |
| 2404 | MAC地址不存在 | 找不到对应MAC地址的设备 |
| 2405 | MAC地址未绑定用户 | 设备需要先绑定用户才能获取Token |
| 2406 | 无法获取RTC服务 | 火山引擎RTC服务不可用，请稍后重试 |
| 2407 | 用户配额不足 | 用户配额已用完，请联系客服 |
| 2408 | 房间创建失败 | 创建RTC房间失败，请稍后重试 |
| 2409 | 任务创建失败 | 创建AI任务失败，请稍后重试 |

## 消息交互错误码 (2500-2599)

| 错误码 | 描述 | 处理建议 |
|--------|------|----------|
| 2501 | 无效的消息类型 | 消息类型必须是支持的类型之一 |
| 2502 | 消息格式错误 | 检查消息格式是否符合要求 |
| 2503 | 用户不存在 | 检查用户ID是否正确 |
| 2504 | 用户无绑定设备 | 用户需要先绑定设备才能发送消息 |
| 2505 | 消息发送失败 | 消息队列服务异常，请稍后重试 |
| 2506 | 消息内容过长 | 消息内容超过最大长度限制 |
| 2507 | 消息发送频率过高 | 降低消息发送频率 |
| 2508 | 设备离线 | 设备当前离线，无法接收消息 |
| 2509 | 功能不支持 | 设备不支持此类型消息 |

## WebSocket错误码 (2600-2699)

| 错误码 | 描述 | 处理建议 |
|--------|------|----------|
| 2601 | WebSocket连接失败 | 检查网络连接是否正常 |
| 2602 | WebSocket认证失败 | 检查Token是否有效 |
| 2603 | WebSocket连接超时 | 重新建立连接 |
| 2604 | WebSocket连接已关闭 | 可能是网络问题或服务器主动关闭，尝试重连 |
| 2605 | WebSocket发送消息失败 | 检查连接状态，尝试重连 |
| 2606 | WebSocket接收消息格式错误 | 消息格式不符合规范 |
| 2607 | WebSocket服务不可用 | 服务器WebSocket服务异常，请稍后重试 |
| 2608 | 同一用户多点登录限制 | 同一用户只允许建立有限数量的WebSocket连接 |

## 错误处理建议

1. **客户端错误处理**:
   - 对于4xx错误，客户端应向用户展示友好的错误提示
   - 特定错误码应有特定的处理逻辑
   - 对于参数错误，应检查并修正参数后重试
   - 认证类错误应引导用户重新登录

2. **服务端错误处理**:
   - 对于5xx错误，应向用户展示"服务暂时不可用"等通用提示
   - 记录错误日志，包括错误码、错误时间、请求参数等
   - 设置重试机制，特别是对于网络类错误
   - 严重错误应上报监控系统

3. **特殊情况**:
   - 对于Token获取失败，可能需要降级处理
   - 对于WebSocket连接问题，应实现自动重连机制
   - 批量操作失败，应提供部分成功的结果信息

## 常见问题排查

1. **设备绑定失败**:
   - 检查MAC地址是否正确
   - 确认设备是否已激活
   - 确认设备是否已被其他用户绑定
   - 检查用户绑定设备数量是否已达上限

2. **Token获取失败**:
   - 检查设备MAC地址是否正确
   - 确认设备是否已绑定用户
   - 检查火山引擎服务是否正常
   - 确认用户配额是否充足

3. **消息发送失败**:
   - 检查设备是否在线
   - 确认消息格式是否正确
   - 检查用户是否有绑定设备
   - 确认设备是否支持该类型消息