# EZOpenSDK HarmonyOS 错误码与常见问题

适用于 Android、iOS、Harmony、Mac 四端 SDK。萤石开放平台 SDK 错误码都是 6 位数，对各个二方库的错误码做了【偏移量处理】。负数错误码都为网络问题（手机或者平台服务），请检查手机网络或者检查请求地址是否正确。

## 一、HarmonyOS 平台常见问题 FAQ

### 预览问题

**Q：设备预览失败**
1. 查阅错误码表
2. 确认是否是网络问题，切换至外网试试
3. 如果 Demo 正常但自己 App 不正常，检查 setPlayVerifyCode 传入的是否是明文字符串
4. 确认播放器是否正确设置了 XComponent surfaceId（`player.setPlayerView(surfaceId)`）

**Q：预览花屏、绿屏、卡顿**
A：设备端网络不稳定或设备问题，使用萤石云视频 App 对比验证。

**Q：async 方法不加 await 导致异常**
A：所有标记为 async 的 SDK 方法（initLibWithAppKey、setAccessToken、startRealPlay 等）调用时必须加 await，且调用链路上的父函数也必须标记为 async。

### 对讲问题

**Q：第一次对讲异常/无声音**
A：务必在发起对讲前向系统申请 `ohos.permission.MICROPHONE` 麦克风权限，否则第一次对讲异常。

**Q：对讲有回音**
A：非国标设备对讲成功后需关闭预览播放器声音 `await player.closeSound()`，对讲结束后恢复。

### 配网问题

**Q：AP 配网自动连接设备热点失败**
A：鸿蒙通过 `wifiManager.addCandidateConfig` 连接，部分场景可能失败。需引导用户手动去系统设置页连接设备热点。

### 问题反馈须知

排查步骤：
1. 查阅错误码表
2. 查看本文常见问题
3. 使用官网最新 Demo 复现
4. 若 Demo 可复现，创建工单并提供：SDK 平台类型、问题频率、详细描述、Demo 完整日志

## 二、SDK 常用错误码常量

```typescript
EZErrorCode.EZ_SDK_NEED_VALIDATECODE = 400035     // 需要设备验证码
EZErrorCode.EZ_SDK_VALIDATECODE_NOT_MATCH = 400036 // 设备验证码不匹配
EZErrorCode.EZ_SDK_NOT_SUPPORT_TALK = 400025       // 设备不支持对讲

EZErrorCode.EZ_HTTPS_DEVICE_ADDED_MYSELF = 120020       // 设备在线，已被自己添加
EZErrorCode.EZ_HTTPS_DEVICE_ONLINE_ADDED = 120022       // 设备在线，已被别人添加
EZErrorCode.EZ_HTTPS_DEVICE_OFFLINE_NOT_ADDED = 120023  // 设备不在线，未被添加
EZErrorCode.EZ_HTTPS_DEVICE_OFFLINE_IS_ADDED = 120024   // 设备不在线，已被别人添加
EZErrorCode.EZ_HTTPS_DEVICE_OFFLINE_IS_ADDED_MYSELF = 120029 // 设备不在线，已被自己添加
EZErrorCode.EZ_HTTPS_DEVICE_NOT_EXISTS = 120002          // 设备不存在
EZErrorCode.EZ_HTTPS_DEVICE_ONLINE_IS_ADDED = 120021     // 设备在线，未被添加
EZErrorCode.EZ_HTTPS_DEVICE_VALICATECODE_ERROR = 105002  // 设备验证码错误
```

## 三、错误码偏移值对照表

| 错误码偏移值 | 含义 | 备注 |
|:---|:---|:---|
| 100000 | http请求错误码 | 错误码减去100000 |
| 320000 | 通用库自定义错误码 | 错误码减去320000 |
| 321000 | 研究院播放库错误码 | 错误码减去321000 |
| 340000 | RTSP错误码 | 错误码减去340000 |
| 360000 | tts对讲协议错误码 | 错误码减去360000 |
| 361000 | 新tts对讲协议错误码 | |
| 380000 | 直连、P2P取流错误码 | 错误码减去380000 |
| 390000 | 流媒体转发取流错误码 | 错误码减去390000 |
| 400000 | EZOpenSDK自定义错误码 | |

## 四、错误码表

### 用户账号相关（101xxx）
| 错误码 | 释义 |
|--------|------|
| 101001 | 用户名不合法 |
| 101002 | 用户名已被占用 |
| 101003 | 密码不合法 |
| 101006 | 手机号码已经被注册 |
| 101007 | 手机号未注册 |
| 101008 | 手机号码不合法 |
| 101010 | 获取验证码失败 |
| 101011 | 验证码错误 |
| 101012 | 验证码失效 |
| 101013 | 用户不存在 |
| 101014 | 密码不正确或 appKey 不正确 |
| 101015 | 用户被锁住 |
| 101041 | 获取验证码过于频繁 |
| 101043 | 手机验证码输入错误超过规定次数 |

### 设备相关（102xxx/105xxx/106xxx）
| 错误码 | 释义 | 解决方案 |
|--------|------|----------|
| 102000 | 设备不存在 | |
| 102001 | 摄像机不存在 | 摄像机未注册到萤石云平台 |
| 102003 | 设备不在线 | |
| 102009 | 设备请求响应超时异常 | |
| 105000 | 设备已被自己添加 | |
| 105001 | 设备已被别人添加 | |
| 105002 | 设备验证码错误 | |
| 106002 | 请在萤石客户端关闭终端绑定 | |

### 平台接口相关（110xxx）
| 错误码 | 释义 | 解决方案 |
|--------|------|----------|
| 110001 | 参数错误 | |
| 110002 | accessToken 异常或过期 | 有效期七天，过期重新获取 |
| 110004 | 用户不存在 | |
| 110005 | appKey 异常 | |
| 110006 | ip受限 | |
| 110007 | 调用次数达上限 | 请升级企业版 |
| 110013 | 应用没有权限调用此接口 | |
| 110017 | appKey 不存在 | 请填写官网申请的应用秘钥 |
| 110018 | AccessToken 与 Appkey 不匹配 | 检查 appKey 是否一致 |
| 110026 | 设备数量超出个人版限制 | 请升级企业版 |
| 110029 | 调用频率超过限制20次/分钟 | 请升级企业版 |
| 110031 | 子账户或萤石用户没有权限 | |

### 设备操作相关（120xxx）
| 错误码 | 释义 | 解决方案 |
|--------|------|----------|
| 120001 | 通道不存在 | |
| 120002 | 设备不存在 | |
| 120006 | 网络异常 | |
| 120007 | 设备不在线 | |
| 120008 | 设备响应超时 | 检测设备网络或重试 |
| 120010 | 设备验证码错误 | 验证码在设备标签上 |
| 120013 | 设备已被别人添加 | |
| 120015 | 设备不支持该功能 | |
| 120017 | 设备已被自己添加 | |
| 120018 | 该用户不拥有该设备 | |
| 120020 | 设备在线，被自己添加 | |
| 120021 | 设备在线，未被用户添加 | |
| 120022 | 设备在线，已被别人添加 | |
| 120023 | 设备不在线，未被添加 | |
| 120024 | 设备不在线，已被别人添加 | |
| 120029 | 设备不在线，已被自己添加 | |
| 120031 | 开启终端绑定 | 请在萤石客户端关闭终端绑定 |
| 120035 | 该通道被隐藏 | 开放平台不支持隐藏通道取流 |
| 120501 | 开锁失败 | |
| 120508 | 开关锁失败 | |
| 120509 | 开关锁超时 | |
| 120511 | 远程开锁功能未打开 | |

### 云台相关（160xxx）
| 错误码 | 释义 |
|--------|------|
| 160000 | 设备不支持云台控制 |
| 160001 | 用户无云台控制权限 |
| 160002~160005 | 云台旋转达到上/下/左/右限位 |
| 160006 | 云台当前操作失败 |
| 160020 | 不支持该命令 |
| 160026 | 设备处于隐私遮蔽状态 |
| 160029 | 设备处于语音对讲状态 |
| 160087 | 设备未开通对讲变声 |

### 服务器相关（150xxx/250xxx）
| 错误码 | 释义 |
|--------|------|
| 150000 | 服务器异常 |
| 250000 | 服务器异常 |

### SDK 内部错误（320xxx）
| 错误码 | 释义 | 解决方案 |
|--------|------|----------|
| 320001 | 未知错误 | |
| 320002 | 参数无效 | |
| 320007 | token失效 | 小权限模式：IPC对讲用0通道 |
| 320008 | token池没有token | 请传入token |
| 320014 | SDK 未初始化 | |
| 320020 | 预连接被清除 | 提示网络不佳请重试 |
| 320021 | 流加密码不对 | |
| 320022 | 未传入播放窗口 | |
| 320023 | 流头超时 | 设备网络问题/通道推不出流 |
| 320024 | 流数据超时 | 设备端网络推流不稳定 |
| 320025 | 解码超时 | 设备端网络问题 |

### 研究院播放库错误码（321xxx）
| 错误码 | 释义 | 解决方案 |
|--------|------|----------|
| 321001 | 播放库入参不对 | 检查 setPlayVerifyCode 传入的是否是明文字符串 |
| 321022 | 播放窗口未解绑 | 确认 player 的 surfaceId 是否正确设置 |

### 对讲相关（360xxx/361xxx）
| 错误码 | 释义 | 解决方案 |
|--------|------|----------|
| 360003 | 设备链接服务失败 | 设备网络问题 |
| 360008 | 认证 token 失败 | 小权限模式：IPC对讲用0通道 |
| 360010 | 设备正在对讲中 | |
| 360011 | 设备响应超时 | |
| 360012 | 设备不在线 | |
| 360013 | 设备开启隐私保护 | |
| 360028 | 设备资源受限 | |
| 360108 | 客户端连接对讲服务失败 | 客户端网络问题 |
| 360111 | 客户端对讲中接收错误 | 网络异常，切换到外网 |
| 361003 | 设备链接对讲服务器超时 | 检查隐私遮蔽/设备网络 |
| 361010 | 设备已经在对讲 | |
| 361012 | 设备不在线 | |
| 361013 | 设备开启隐私保护拒绝对讲 | |

### P2P/直连相关（380xxx）
| 错误码 | 释义 | 解决方案 |
|--------|------|----------|
| 380004 | 系统内部错误 | 通道错误/不在线/码流不支持 |
| 380121 | 请求的设备不在线 | |
| 380123 | 设备达到最大连接数 | |
| 380127 | 设备开启隐私保护 | |
| 380209 | 连接服务器或设备失败 | 网络不通 |
| 380213 | 信令接收超时 | P2P取流10秒内未收到响应 |
| 380224 | P2P 打洞失败 | |
| 380229 | SSL 连接失败 | 网络不佳 |
| 380290 | P2P 预链接路数达上限 | |
| 380291 | 直连取流路数达上限 | |
| 380293 | 设备未绑定用户 | 检测设备是否已加入平台 |
| 380355 | socket 错误 | 取流链路异常，检查网络 |
| 380367 | 用户无权限访问设备 | |
| 380368 | Token无效或过期 | |

### 流媒体转发取流相关（390xxx）
| 错误码 | 释义 | 解决方案 |
|--------|------|----------|
| 390034 | 向 VTM 请求超时 | 检查 App 网络 |
| 390037 | 向 VTDU 取流请求超时 | 设备端网络问题 |
| 390038 | 向 VTDU 保活请求超时 | 网络不佳 |

### 流媒体服务端错误（395xxx）
| 错误码 | 释义 | 解决方案 |
|--------|------|----------|
| 395402 | 回放找不到录像文件 | 检查存储卡 |
| 395404 | 设备不在线 | 检查设备网络 |
| 395405 | 流媒体信令超时 | 设备网络异常 |
| 395406 | token失效 | 刷新重试 |
| 395409 | 预览开启隐私保护 | |
| 395410 | 设备达到最大连接数 | |
| 395411 | token 无权限 | 确保已setAccessToken |
| 395451 | 不支持的码流类型 | 切换清晰度重试 |
| 395452 | 设备链接流媒体失败 | 设备网络异常 |
| 395500 | 流媒体服务器内部错误 | 刷新重试 |
| 395503 | vtm返回分配vtdu失败 | 服务器负载上限 |
| 395544 | 设备返回无视频源 | |
| 395546 | 达到取流并发限制 | 请升级企业版 |
| 395557 | 回放等待流头超时 | 刷新重试，检测设备网络 |

### 客户端错误（400xxx）
| 错误码 | 释义 | 解决方案 |
|--------|------|----------|
| 400001 | 参数为空 | |
| 400002 | 参数错误 | 检查 API 入参 |
| 400025 | 设备不支持对讲 | 确认设备对讲能力 |
| 400029 | 未初始化或资源被释放 | 确认播放器是否正确创建 |
| 400031 | 网络异常 | 检查手机网络 |
| 400034 | 取流超时 | 设备网络差或设备异常 |
| 400035 | 设备已加密，需输入验证码 | 调用 setPlayVerifyCode |
| 400036 | 播放验证码错误 | 重新输入正确的验证码 |
| 400037 | 播放视图错误 | 检查 XComponent surfaceId 设置 |
| 400901 | 设备不在线 | |
| 400902 | accessToken 异常或失效 | |
| 400903 | 当前账号开启了终端绑定 | |
| 400904 | 设备正在对讲中 | |
| 400905 | 设备开启隐私保护 | |

> 完整错误码表请参考：https://open.ys7.com/help/37
