# 错误码 (/zh-CN/realtime-media/rtc/reference/error-code/web)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

在调用声网 API 过程中，SDK 可能会返回错误码。当收到错误码时，意味着 SDK 遭遇了不可恢复的错误，需要 App 干预。

本文列出常见错误码的详细含义及其解决方法。对于未给出解决方法的错误码，声网推荐你[联系技术支持](https://ticket.shengwang.cn)，我们的技术服务会根据你在实际场景中遇到的问题进行排查。























SDK 可能以下列方式抛出错误码：

- 对于异步方法，SDK 返回 Promise 来通知异步操作的结果，Promise 被 reject 时 SDK 会抛出相应的错误码。
- 同步方法调用失败时，SDK 直接抛出错误码。
- SDK 内部运行过程中，也可能抛出一些网络相关的错误码。

你可参考本文了解这些错误码的详细含义及处理方法。

SDK 的错误码对象 `AgoraRTCError` 继承自浏览器的 [Error 对象](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)。你需要通过 `AgoraRTCError.code` 在控制台上打印出错误码，直接打印 `AgoraRTCError` 对象只能看到错误信息。

## 通用错误码 [#通用错误码-11]

| 错误码 | 描述 | 处理方法 |
| --- | --- | --- |
| `UNEXPECTED_ERROR` | 无法处理的、非预期的错误，通常这个错误会有具体的错误提示。 | 无。 |
| `UNEXPECTED_RESPONSE` | 服务端返回了非预期的响应。这个错误通常是在网络问题导致客户端与服务端状态不一致时抛出。 | 等待网络稳定后重试该操作。 |
| `INVALID_PARAMS` | 非法参数。 | 根据具体提示确认操作，并根据文档传入正确的参数。 |
| `NOT_SUPPORTED` | 浏览器不支持。 | 参考[浏览器支持情况](/zh-CN/realtime-media/rtc/reference/browser-compatibility)。 |
| `INVALID_OPERATION` | 非法操作，通常是因为在当前状态不能进行该操作。 | 确认操作的先后顺序，比如发布前请确认已经加入频道。 |
| `OPERATION_ABORTED` | 操作中止，通常是因为网络质量差或连接断开导致与声网服务器通信失败。 | 通过 [AgoraRTCClient.on("user-joined")](/zh-CN/api-reference/rtc/web/interfaces/iagorartcclient#event_user_joined) 回调确认本地网络状况，并重试该操作。 |
| `WEB_SECURITY_RESTRICT` | 浏览器安全策略限制。 | 请确保 Web 页面运行在[安全环境](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts)中。 |
| `NO_ACTIVE_STATUS` | 声网项目未激活或被禁用。 | 请前往声网控制台确认项目状态是否为启用。 |

## 请求相关错误码 [#请求相关错误码]
### 网络连接 [#网络连接]

| 错误码 | 描述 | 处理方法 |
| --- | --- | --- |
| `NETWORK_TIMEOUT` | 请求超时，通常是因为网络质量差或连接断开导致与声网服务器通信失败。 | 通过 [AgoraRTCClient.on("user-joined")](/zh-CN/api-reference/rtc/web/interfaces/iagorartcclient#event_user_joined) 回调确认本地网络状况，并重试该操作。 |
| `NETWORK_RESPONSE_ERROR` | 响应错误，一般是状态码非法。 | 确认操作的参数是否正确，并根据文档传入正确的参数。 |
| `NETWORK_ERROR` | 无法定位的网络错误。 | 无。 |

### SDK 内部请求 [#sdk-内部请求]

| 错误码 | 描述 | 处理方法 |
| --- | --- | --- |
| `WS_ABORT` | 请求声网服务器过程中 WebSocket 断开。 | 监听 [AgoraRTCClient.on("connection-state-change")](/zh-CN/api-reference/rtc/web/interfaces/iagorartcclient#event_connection_state_change) 事件，待连接状态变为 `CONNECTED` 后重试。 |
| `WS_DISCONNECT` | 请求声网服务器前，WebSocket 就已经断开。 | 监听 [AgoraRTCClient.on("connection-state-change")](/zh-CN/api-reference/rtc/web/interfaces/iagorartcclient#event_connection_state_change) 事件，待连接状态变为 `CONNECTED` 后重试。 |
| `WS_ERR` | WebSocket 连接发生错误。 | 检查当前浏览器对 WebSocket 的支持情况。 |

## 设备管理相关错误码 [#设备管理相关错误码]

| 错误码 | 描述 | 处理方法 |
| --- | --- | --- |
| `ENUMERATE_DEVICES_FAILED` | 枚举本地设备失败，一般是由于浏览器限制。 | 无。 |
| `DEVICE_NOT_FOUND` | 无法找到指定设备。 | 传入正确的设备 ID。 |

## Track 相关错误码 [#track-相关错误码]

| 错误码 | 描述 | 处理方法 |
| --- | --- | --- |
| `TRACK_IS_DISABLED` | 轨道被禁用，通常因为轨道设置了 [Track.setEnabled(false)](/zh-CN/api-reference/rtc/web/interfaces/ilocaltrack#setenabled)。 | 对该轨道调用 [Track.setEnabled(true)](/zh-CN/api-reference/rtc/web/interfaces/ilocaltrack#setenabled) 后再进行操作。 |
| `SHARE_AUDIO_NOT_ALLOWED` | 屏幕共享音频时终端用户没有点击分享音频。 | 要求终端用户在弹出的屏幕共享窗口中勾选分享音频。 |
| `MEDIA_OPTION_INVALID` | 不支持的媒体采集的参数。 | 修改媒体采集参数或使用 SDK 预设的配置。 |
| `CONSTRAINT_NOT_SATISFIED` | 不支持的媒体采集的参数。 | 修改媒体采集参数或使用 SDK 预设的配置。 |
| `PERMISSION_DENIED` | 获取媒体设备权限被拒绝。 | 在弹出的获取设备权限窗口中选择允许。 |
| `NOT_READABLE` | 用户已经授权，但媒体设备无法访问。 | 检查当前采集设备和驱动程序是否出错。 |
| `FETCH_AUDIO_FILE_FAILED` | 下载在线音频文件失败。 | 填入正确的在线音频地址，并确保可以正常访问。 |
| `READ_LOCAL_AUDIO_FILE_ERROR` | 读取本地音频文件失败。 | 填入正确的本地音频文件路径。 |
| `DECODE_AUDIO_FILE_FAILED` | 音频文件解码失败，可能是因为音频文件的编码格式是浏览器 WebAudio 不支持的编码格式。 | 检查浏览器 WebAudio 是否支持音频文件的编码格式。 |

## Client 相关错误码 [#client-相关错误码]
### 加入频道 [#加入频道]
下表列出加入频道失败时 SDK 抛出的错误码。

| 错误码 | 描述 | 处理方法 |
| --- | --- | --- |
| `UID_CONFLICT` | 同一个频道内 UID 重复。 | 使用不同的 UID 进入频道。 |
| `INVALID_UINT_UID_FROM_STRING_UID` | String UID 分配服务返回了非法的 int UID。 | 使用不同的 UID 进入频道。 |
| `CAN_NOT_GET_PROXY_SERVER` | 无法获取云代理服务地址。 | 无。 |
| `CAN_NOT_GET_GATEWAY_SERVER` | 无法获取声网服务器地址。 | 无。 |

### 发布/取消发布 [#发布取消发布]
下表列出发布或取消发布失败时 SDK 抛出的错误码。

| 错误码 | 描述 | 处理方法 |
| --- | --- | --- |
| `INVALID_LOCAL_TRACK` | 传入了非法的 LocalTrack。 | 检查传入的 Track，并传入正确的 LocalTrack。 |
| `CAN_NOT_PUBLISH_MULTIPLE_VIDEO_TRACKS` | 一个 Client 发布多个视频轨道。 | 一个 Client 同一时间只能发布一个视频轨道，如果想发布多个视频轨道请创建多个 Client。 |

### 订阅/取消订阅 [#订阅取消订阅]
下表列出订阅或取消订阅失败时 SDK 抛出的错误码。

| 错误码 | 描述 | 处理方法 |
| --- | --- | --- |
| `INVALID_REMOTE_USER` | 非法的远端用户，可能是远端用户不在频道内或还未发布任何媒体轨道。 | 收到 [AgoraRTCClient.on("user-published")](/zh-CN/api-reference/rtc/web/interfaces/iagorartcclient#event_user_published) 事件后再进行订阅操作。 |
| `REMOTE_USER_IS_NOT_PUBLISHED` | 远端用户已发布了音频或视频轨道，但不是与你的订阅操作所指定的类型不符。 | 请确保订阅操作传入的轨道类型需要与 [AgoraRTCClient.on("user-published")](/zh-CN/api-reference/rtc/web/interfaces/iagorartcclient#event_user_published) 事件给出的类型一致，或者在订阅前通过 [AgoraRTCRemoteUser.hasVideo](/zh-CN/api-reference/rtc/web/interfaces/iagorartcremoteuser#hasvideo) 和 [AgoraRTCRemoteUser.hasAudio](/zh-CN/api-reference/rtc/web/interfaces/iagorartcremoteuser#hasaudio) 确认远端用户是否发布了该类型的轨道。 |
| `ERR_TOO_MANY_BROADCASTERS` | 频道内主播人数超过上限。 | 控制主播人数。例如：仅在用户需要发布音视频轨道的时候调用 [Client.setClientRole](/zh-CN/api-reference/rtc/web/interfaces/iagorartcclient#setclientrole)，将用户角色切换为主播。 |
| `ERR_TOO_MANY_SUBSCRIBERS` | 当前用户订阅的主播人数超过上限。 | 按需订阅主播。 |

## 推流到 CDN [#推流到-cdn]
下表列出推流到 CDN 失败时 SDK 抛出的错误码。

| 错误码 | 描述 | 处理方法 |
| --- | --- | --- |
| `LIVE_STREAMING_TASK_CONFLICT` | 推流任务已经存在。 | 先调用 [Client.stopLiveStreaming](/zh-CN/api-reference/rtc/web/interfaces/iagorartcclient#stoplivestreaming) 停止该推流任务再重新进行推流操作。 |
| `LIVE_STREAMING_INVALID_ARGUMENT` | 推流参数错误。 | 参考 [Client.startLiveStreaming](/zh-CN/api-reference/rtc/web/interfaces/iagorartcclient#startlivestreaming) 的 API 文档检查推流操作的参数。 |
| `LIVE_STREAMING_INTERNAL_SERVER_ERROR` | 推流服务器内部错误。 | 重新进行推流操作，如果仍然失败，刷新页面重试。 |
| `LIVE_STREAMING_PUBLISH_STREAM_NOT_AUTHORIZED` | 推流 URL 被占用。 | 检查填入的 URL 是否被占用。 |
| `LIVE_STREAMING_CDN_ERROR` | 推流的目标 CDN 出现错误导致推流失败。 | 确认目标 CDN 的健康状况。 |
| `LIVE_STREAMING_INVALID_RAW_STREAM` | 推流超时。 | 确认目标流是否存在。 |

## 跨频道连麦 [#跨频道连麦]
下表列出跨频道连麦失败时 SDK 抛出的错误码。

| 错误码 | 描述 |
| --- | --- |
| `CROSS_CHANNEL_WAIT_STATUS_ERROR` | 等待 [AgoraRTCClient.on("channel-media-relay-state")](/zh-CN/api-reference/rtc/web/interfaces/iagorartcclient#event_channel_media_relay_state) 回调出错。 |
| `CROSS_CHANNEL_FAILED_JOIN_SRC` | 发起跨频道转发媒体流请求失败。 |
| `CROSS_CHANNEL_FAILED_JOIN_DEST` | 接受跨频道转发媒体流请求失败。 |
| `CROSS_CHANNEL_FAILED_PACKET_SENT_TO_DEST` | 服务器接收跨频道转发媒体流失败。 |
| `CROSS_CHANNEL_SERVER_ERROR_RESPONSE` | 服务器响应出错。 |