在调用 Agora API 过程中,SDK 可能会返回错误码和警告码。其中错误码意味着 SDK 遭遇了不可恢复的错误,需要 app 干预;警告码意味着 SDK 遇到问题,但有可能恢复。警告码仅起告知作用,一般情况下 app 可以忽略警告码。

无论是何种情况,你都可以参考本文,了解这些错误码和警告码的详细含义,及其解决方法。对于未给出解决方法的错误码,Agora 推荐你提交工单,我们的技术服务会根据你在实际场景中遇到的问题进行排查。

SDK 在返回错误码时,可能会返回一个负数。这个负数就对应着错误码或警告码里的正整数。例如返回 -2,则对应错误码或警告码里的 2

Native 及第三方框架

本节适用于如下平台的 Agora RTC SDK:

  • 原生平台,如 Android、iOS、macOS、Windows。
  • 第三方框架,即基于原生平台封装的第三方平台,如 Electron、Unity、React Native、Flutter 等。

Agora SDK 在运行过程中,可能通过如下方式返回错误码或警告码:

  • 在方法调用失败的返回值中,返回一个负数,这个负数就对应着错误码与警告码里的正数。
  • 通过 onError 或者 onWarning 回调报告错误码或警告码。

基础错误码

枚举值 说明
0 没有错误。
1 一般性的错误(没有明确归类的错误原因)。请重新调用方法。
2 方法中设置了无效的参数。例如指定的频道名中含有非法字符。请重新设置参数。
3 SDK 尚未准备好。可能的原因有:
  • RtcEngine 初始化失败。请重新初始化 RtcEngine
  • 调用方法时用户尚未加入频道。请检查方法的调用逻辑。
  • 调用 ratecomplain 方法时用户尚未离开频道。请检查方法的调用逻辑。
  • 请检查是否已开启音频模块。
  • 请检查程序集完整性。
4 RtcEngine 当前状态不支持该操作。可能的原因有:
  • Android 平台调用 setBeautyEffectOptions 方法时,如果设备版本低于 Android 4.4,会报这个错。请确认 Android 设备版本。
  • 使用内置加密时,设置的加密模式不正确,或加载外部加密库失败。请检查加密的枚举值是否正确,或重新加载外部加密库。
5 方法调用被拒绝。可能的原因有:
  • RtcEngine 初始化失败。请重新初始化 RtcEngine
  • 在创建 RtcChannel 对象时,将频道名设为空字符 ""。请重新设置频道名。
  • 多频道场景下,在调用 joinChannel 方法加入频道时,设置的频道名已存在。请重新设置频道名。
  • 已经通过 RtcChannel 加入了一个频道,并在该 RtcChannel 频道中发布了音视频流,又尝试通过 RtcEnginejoinChannel 方法加入第二个频道。如果已经通过 RtcChannel 对象加入了一个频道,且在该频道内发了流,就不能再通过 RtcEnginejoinChannel 方法加入第二个频道。
  • 在调用 switchChannel 方法切换直播频道时,用户角色不是观众。调用 switchChannel 方法时,请确保当前的用户角色为观众。
6 缓冲区大小不足以存放返回的数据。
7 RtcEngine 尚未初始化就调用方法。请确认在调用该方法前已创建 RtcEngine 对象,并完成初始化。
9 没有操作权限。请检查用户是否授予了 app 音视频设备的使用权限。
10 方法调用超时。有些方法调用需要 SDK 返回结果,如果 SDK 处理事件过长,超过 10 秒没有返回,会出现此错误。
17 加入频道被拒绝。一般有以下原因:
  • 用户已经在频道中,再次调用加入频道的方法,如 joinChannel 时,会返回此错误。停止调用该方法即可。
  • 用户在调用 startEchoTest 进行通话测试时,未调用 stopEchoTest 结束当前测试,就尝试加入频道。开始通话测试后,需要先调用 stopEchoTest 结束当前测试,再加入频道。
18 离开频道失败。一般有以下原因:
  • 用户已离开频道,再次调用退出频道的方法,如 leaveChannel 时,会返回此错误。停止调用该方法即可。
  • 用户尚未加入频道,就调用退出频道的方法。这种情况下无需额外操作。
19 资源已被占用,不能重复使用。
20 SDK 放弃请求,可能由于请求的次数太多。
21 Windows 下特定的防火墙设置导致 RtcEngine 初始化失败然后崩溃。
22 当 app 占用资源过多或系统资源耗尽时,SDK 分配资源失败,会返回该错误。
101 不是有效的 App ID。请更换有效的 App ID 重新加入频道。
102 不是有效的频道名。可能的原因是设置的参数数据类型不正确。请更换有效的频道名重新加入频道。
103 无法获取当前区域的服务器资源。请在初始化 RtcEngine 时尝试指定其他区域。
109 弃用:从 v2.4.1 起废弃。请改用 onConnectionStateChanged 回调中的 CONNECTION_CHANGED_TOKEN_EXPIRED(9)
当前使用的 Token 过期,不再有效。请在服务端申请生成新的 Token,并调用 renewToken 更新 Token。
110 弃用:从 v2.4.1 起废弃。请改用 onConnectionStateChanged 回调中的 CONNECTION_CHANGED_INVALID_TOKEN(8)
Token 无效。一般有以下原因:
  • 在 Agora 控制台中启用了 App 证书,但仍旧在代码里使用了 App ID。当项目启用了 App 证书,就必须使用 Token 鉴权。
  • 生成 Token 时填入的 uid 字段,和用户加入频道时填入的 uid 不匹配。
111 网络连接中断。SDK 在和服务器建立连接后,失去了网络连接超过 4 秒,会报告该错误。
112 网络连接丢失。 网络连接中断,且 SDK 无法在 10 秒内连接服务器,会报告fail错误。
113 调用方法时用户不在频道内。
114 在调用 sendStreamMessage 时,当发送的数据长度大于 1024 个字节时,会返回该错误。
115 在调用 sendStreamMessage 时,当发送数据的频率超过限制(6 KB/s)时,会返回该错误。
116 在调用 createDataStream 时,如果创建的数据通道过多(超过 5 个)时,会返回该错误。
117 数据流发送超时。
119 用户切换角色失败。
120 解密失败。可能是用户加入频道时使用了错误的密码。请检查用户加入频道时填入的密码,或引导用户尝试重新加入频道。
123 此用户被服务器禁止。当用户被服务端踢出时会报这个错。
134 无效的用户 user account,可能是因为设置了无效的参数。

水印相关错误码

枚举值 说明
124 水印文件参数错误。
125 水印文件路径错误。
126 水印图片文件格式错误。SDK 只支持添加 PNG 格式的水印图片。
127 水印文件信息错误。
128 水印文件数据格式错误。
129 水印文件读取错误。

推流相关错误码

枚举值 说明
130 如果开启了媒体流加密,则在调用 addPublishStreamUrl 时,会返回该错误。SDK 不支持将加密过的流推到 CDN 上。
151 推流到 CDN 报错。请调用 removePublishStreamUrl 删除当前的推流地址,然后调用 addPublishStreamUrl 重新尝试推流。
152 单个主播的推流地址数目达到上限 10。请删掉一些不用的推流地址,再增加新的推流地址。
153 主播操作不属于自己的流,如更新其他主播的流的参数,或停止其他主播的流。请检查 app 逻辑。
154 推流服务器出现错误。请调用 addPublishStreamUrl 重新推流。
155 服务器无法找到数据流。
156 推流地址格式有错误。请检查推流地址格式是否正确。

音频相关错误码

枚举值 说明
1005 音频设备出现错误(未指明何种错误)。请检查音频设备是否被其他应用占用,或者尝试重新进入频道。
1006 使用 Java 资源出错。请确认设备内存是否够用,或重启设备。
1007 设置的采样频率出现错误。
1008 初始化播放设备出错。请检查播放设备是否被其他应用占用,或者尝试重新进入频道。
1009 启动播放设备出错。请检查播放设备是否正常,或者尝试重新进入频道。
1010 停止播放设备出错。
1011 初始化录音设备出错。请检查录音设备是否正常,或者尝试重新进入频道。
1012 启动录音设备出错。请检查录音设备是否正常,或者尝试重新进入频道。
1013 停止录音设备出错。
1015 播放出错。请检查播放设备是否正常,或者尝试重新进入频道。
1017 录音错误。请检查音频采集设备是否正常,或者尝试重新进入频道。
1018 录音失败。
1022 初始化 Loopback 设备错误。
1023 启动 Loopback 设备错误。
1027 没有录音权限。请检查是否已经打开录音权限,或者录音设备是否被第三方应用占用。
1033 录音设备被占用。
1101 使用 Java 资源出现错误。请确认设备内存是否够用,或重启设备。
1108 采集频率低于 50,常见为 0,即录音未启动,建议检查录音权限。
1109 播放频率低于 50,常见为 0,即播放未启动,建议检查是否 AudioTrack 实例过多。
1111 录音启动失败,系统 ROM 报错,建议重启 app 或重启手机、检查录音权限。
1112 播放启动失败,系统 ROM 报错,建议重启 app 或重启手机、检查播放权限。
1115 录音失败。请确认设备权限或网络连接状况。
1201 当前设备不支持音频输入,可能的原因是 Audio Session 的 category 配置不对或音频输入设备被占用。建议终止后台所有应用的进程,重新加入频道。
1206 Audio Session 启动失败。请检查你的音频采集设置。
1210 初始化音频设备出错。一般出错是因为音频设备的设置参数错误。
1213 重新初始化音频设备出错。一般出错是因为音频设备的设置参数错误。
1214 重新启动音频设备出错。一般出错是因为 Audio Session 的 category 设置与音频设备的设置不兼容。
1301 音频设备模块初始化失败。请禁用并重新启用音频设备,或者重启机器。
1303 音频设备模块终止失败。请禁用并重新启用音频设备,或者重启机器。
1306 播放设备初始化失败。请禁用并重新启用音频设备,或者重启机器。
1307 无音频播放设备,导致初始化失败。请插入音频设备。
1309 启动录音失败。请禁用并重新启用音频设备,或者重启机器。
1311 创建录音线程失败,可能的原因是内存或设备性能不足。请重启机器或者更换机器。
1314 启动录音失败。请禁用并重新启用音频设备,或者重启机器,或者更新声卡驱动。
1319 创建播放线程失败,可能的原因是内存或设备性能不足。请重启机器或者更换机器。
1320 启动播放失败。请禁用并重新启用音频设备,或者重启机器,或者更新声卡驱动。
1322 无可用音频采集设备。请连接可用的录音设备。
1323 无可用音频播放设备。请连接可用的播放设备。
1351 音频设备模块初始化失败。请禁用并重新启用音频设备,或者重启机器,或者更新声卡驱动。
1353 初始化录音设备失败。请禁用并重新启用音频设备,或者重启机器,或者更新声卡驱动。
1354 初始化麦克风失败。请禁用并重新启用音频设备,或者重启机器,或者更新声卡驱动。
1355 初始化播放设备失败。请禁用并重新启用音频设备,或者重启机器,或者更新声卡驱动。
1356 初始化扬声器失败。请禁用并重新启用音频设备,或者重启机器,或者更新声卡驱动。
1357 启动录音失败。请禁用并重新启用音频设备,或者重启机器,或者更新声卡驱动。
1358 启动播放失败。请禁用并重新启用音频设备,或者重启机器,或者更新声卡驱动。
1359 无录音设备。请检查是否有可用的录音设备或者录音设备是否已经被其他应用占用。
1360 无播放设备。请检查是否有可用的播放设备或者播放设备是否已经被其他应用占用。

视频相关错误码

枚举值 说明
1003 弃用:从 v2.4.1 起废弃。请改用 onLocalVideoStateChanged 回调中的 LOCAL_VIDEO_STREAM_ERROR_CAPTURE_FAILURE(4)
启动摄像头失败。请检查摄像头是否被其他应用占用,或者尝试重新加入频道。
1004 启用视频渲染模块失败。
1510 没有摄像头使用权限。请检查是否已经打开摄像头权限。
1512 弃用:v2.4.1 起废弃。请改用 onLocalVideoStateChanged 回调中的 LOCAL_VIDEO_STREAM_ERROR_DEVICE_BUSY(3)
摄像头正在使用中。
1600 未知错误。
1601 视频编码初始化失败。请尝试重新加入频道。
1602 视频编码失败。请尝试重新加入频道。
1603 视频编码参数设置失败。

其他错误码

枚举值 说明
1001 加载媒体引擎失败。
1002 启动媒体引擎后开始通话失败。请尝试重新进入频道。

警告码

枚举值 说明
8 指定的 View 无效,使用视频功能时需要指定 View,如果 View 尚未指定,则返回该警告。
16 初始化视频功能失败。有可能是视频资源被占用导致的。用户无法看到视频画面,但不影响语音通信。
20 请求处于待定状态。一般是由于某个模块还没准备好,请求被延迟处理。
103 没有可用的频道资源。可能是因为服务器没法分配频道资源。
104 查找频道超时。在加入频道时 SDK 先要查找指定的频道,出现该警告一般是因为网络太差,无法连接服务器。
105 弃用:从 v2.4.1 起废弃。请改用 onConnectionStateChanged 回调中的 CONNECTION_CHANGED_REJECTED_BY_SERVER(10)
查找频道请求被服务器拒绝。服务器可能没有办法处理这个请求或请求是非法的。
106 加入频道超时。查找到指定频道后,SDK 接着加入该频道,超时一般是因为网络太差,连接不到服务器。
107 加入频道请求被服务器拒绝。服务器可能没有办法处理该请求或该请求是非法的。
111 切换直播视频超时。
118 直播场景下设置用户角色超时。
121 TICKET 非法,加入频道失败。
122 尝试连接另一个服务器。
131 频道连接不可恢复。
132 IP 已改变。
133 端口已改变。
701 打开伴奏文件出错。
1014 运行时播放设备出现警告。
1016 运行时录音设备出现警告。
1019 采集无声音。请确认麦克风是否被占用,录音权限是否给予,采集设备是否正常工作,或者重启设备。
1020 播放频率异常。该异常原因为系统 CPU 占用率高,建议关闭其他可能占用 CPU 的应用。还可以检查 app 是否关闭了音频模块,或尝试重新加入频道。
1021 采集频率异常,该异常原因为系统 CPU 占用率高,建议关闭其他可能占用 CPU 的应用。还可以检查 app 是否关闭了音频模块,或尝试重新加入频道。
1025 播放或录制音频时被系统事件(如来电)干扰。
1029 在通话过程中,Audio Session 的 category 必须设置成 AVAudioSessionCategoryPlayAndRecordRtcEngine 会监控这个属性值。当这个值被修改成其他值的时候会触发这个告警,并强制设置回 AVAudioSessionCategoryPlayAndRecord
1031 采集的音量过小。请确认麦克风是否静音,或者麦克风增强是否打开。
1032 播放的音量过小。请确认对端用户麦克风是否静音,或者其麦克风增强是否打开。
1033 采集设备被占用。请确认音频采集设备的使用权限,或采集设备是否被第三方应用占用。
1040 无音频。禁用并重新启用音频设备,或者重启机器,或者更新声卡驱动。
1051 录制音频时监测到啸叫。请检查两个客户端的距离是否足够远。
1052 系统采集和播放音频线程无法完成调度,通常是由于系统 CPU 占用率高。
1053 检测到残余回声,该回声可能由系统线程调度不及时或信号溢出导致。
1323 无可用音频播放设备。请插入音频设备。
1324 音频采集释放有误。请禁用并重新启用音频设备,或者重启机器,或者更新声卡驱动。
1610 远端用户的原始视频流的分辨率超出了可以应用超分辨率算法的要求。
1611 已指定一个远端用户使用超分辨率算法。
1612 当前设备不支持超分算法。

Web

Agora RTC Web SDK 在运行过程中可能会出现的错误码、警告码及其解决方案,请参考错误码警告码

微信小程序

Agora Miniapp SDK for WeChat 在调用 API 或运行时,可能会返回一个错误码对象,也可能会返回一个错误码:

  • 错误码对象:包含错误码和对报错原因的描述,你可以根据 reason 中的描述自行判断发生引起错误的原因,然后进行排查
  • 错误码:该类错误码中没有相应的reason,你可以对照错误码参考本文进行排查
错误码 报错原因 排查方法
401 请求异常 根据 reason 描述检查使用是否符合要求;如果报的是 invalid vendor key,请开通小程序服务权限,详见微信小程序快速开始
429 请求太频繁 根据 reason 描述检查使用是否符合要求。
430
  • 在订阅前尝试 mute 远端流
  • 在订阅前尝试 unmute 远端流
  • 请求异常
根据 reason 描述检查使用是否符合要求。
431
  • setRole 传入的参数错误
  • 加入频道失败
  • 登录时的 role 传入出错
  • 加入频道时的 uid 传入出错
  • 重复加入频道,且 uid 不匹配
根据 reason 描述检查使用是否符合要求。
432 订阅了一个非主播的 uid 根据 reason 描述检查使用是否符合要求。
433
  • 观众端无法发布流
  • 观众端无法取消发布流
根据 reason 描述检查使用是否符合要求。
434
  • 在加入频道前尝试退出
  • 在加入频道前尝试setRole
  • 发布流时的 uid 和加入频道时的 uid 不一致
  • 取消发布流时的 uid 和加入频道时的 uid 不一致
  • 更新 URL 时的 uid 和加入频道时的 uid 不一致
根据 reason 描述检查使用是否符合要求。
500 内部错误 退出频道并销毁 client 对象后,重建 client 对象,调用 rejoin 方法尝试重连。
501 服务进程异常失去连接 退出频道并销毁 client 对象后,重建 client 对象,调用 rejoin 方法尝试重连。
502 当前服务器过载 退出频道并销毁 client 对象后,重建 client 对象,调用 rejoin 方法尝试重连。
503 服务进程正常退出 N/A
901 未找到服务器 检查是否开启小程序的服务权限;也可能是没有配置域名或 uid 参数格式不正确;你还可以检查网络;检查传入的 App ID、Token 是否有效。
903 发送消息超时 鉴权失败(比如没填 Token);也可能是因为网络连接状况不理想,请检查网络。
904 websocket 断开 退出频道并销毁 client 对象后,重建 client 对象,调用 rejoin 方法尝试重连。
905 websocket 连接失败 退出频道并销毁 client 对象后,重建 client 对象,调用 rejoin 方法尝试重连。