rtc sdk 错误码的那些事儿：含义、排查与解决指南
做音视频开发这些年，我见过太多同事在凌晨盯着错误码抓狂的样子。说实话，rtc sdk 的错误码刚开始看确实有点让人头大——什么 -1001、-2003、10014，光看数字谁记得住啊。但其实仔细研究一下，这些错误码的设计都是有一定规律的，摸清门道之后，排查问题会顺畅很多。
这篇文章不打算把官方文档抄一遍，而是从我实际开发过程中积累的经验出发，聊聊那些最常见的错误码到底代表什么，以及遇到它们该怎么办。文章会采用一种"问题导向"的方式展开，毕竟我们遇到错误的时候，最关心的就是：这是什么问题？严不严重？怎么解决？
一、先搞懂：错误码是怎么设计的？
在深入具体错误码之前，我想先花点时间说错误码的设计逻辑。这就像学数学得先学会阿拉伯数字一样，明白了设计思路，后续记忆和应用都会轻松不少。
目前主流的 RTC SDK 错误码一般采用分段管理的方式。不同区间的数字代表不同类型的问题。比如，负数通常表示 SDK 内部错误或者配置问题，正数可能表示运行时状态或者网络相关的问题。这种设计让开发者能够快速定位问题所属的大类，不需要去记忆每一个具体数字的含义。
另外一个值得注意的点是，错误码通常会区分可恢复错误和不可恢复错误。可恢复错误一般意味着 SDK 检测到了问题但服务仍然可用，只需要做一些调整就能解决；不可恢复错误则通常需要开发者介入处理，或者需要用户重新操作才能继续。搞明白这个区别，能帮你省去不少不必要的焦虑——不是所有错误都需要马上处理，有些可能就是 SDK 在做自我保护。
二、连接类错误：最常见也最好排查
连接类错误是我遇到频率最高的，同时也是相对容易排查的一类。这类错误通常发生在 SDK 尝试与服务器建立连接的过程中，问题要么出在网络环境，要么出在配置参数上。
网络连接超时（常见指数：★★★★★）
当看到连接超时的错误码时，首先别急着怀疑是服务器的问题。我个人的经验是，超过六成的情况都是本地网络环境导致的。你可以按这个思路排查：
- 检查一下用户的网络是否稳定，试试打开网页或者其他 App 能不能正常联网
- 确认没有防火墙或者代理软件阻断连接，有些公司网络会对非标准端口做限制
- 如果是移动端，看看用户是不是在电梯里、地下室或者网络切换中（比如从 WiFi 切到 4G）
如果确认网络没问题，那再看看配置是不是正确。服务器地址有没有写错？端口号对不对？Token 有没有过期？这些都是容易犯的低级错误，但恰恰最容易被人忽略。
认证失败错误（常见指数：★★★★☆）
认证相关的错误通常比较明确，SDK 会明确告诉你是因为 Token 失效、App ID 不匹配还是签名错误。这类问题一般不会让你猜，解决思路也很直接——重新获取有效的认证信息就行了。
不过我遇到过一个比较坑的情况：系统时间不同步导致的认证失败。因为 Token 里面会包含时间戳，如果设备时间和服务器时间相差太大，验证就会失败。这种情况下用户那边的网络可能什么问题都没有，但就是连不上。解决办法很简单——让用户检查一下设备的时间设置，自动同步一下基本就能解决。
连接被拒绝（常见指数：★★★☆☆）
这个错误通常意味着服务器端拒绝了连接请求。原因可能有几种：服务器负载过高进入了保护模式、当前的连接数已经达到了上限、或者你的 App ID 没有开通相应的服务权限。
遇到这种情况，建议先看一下同时在线的用户数量是不是太多了。如果是用量高峰期，可以考虑错峰使用或者临时扩容。如果是权限问题，那就需要检查一下你的账户配置，确保需要的功能已经开通。
三、权限类错误：移动端开发者永远的痛
如果你主要做移动端开发，那权限相关的问题一定没少让你掉头发。特别是 Android 6.0 之后的动态权限机制，让本来简单的事情变得复杂了不少。
摄像头/麦克风权限被拒绝（常见指数：★★★★★）
这是最常见的权限问题。用户可能手抖拒绝了授权，也可能是在系统设置里把权限关掉了，还有可能是后台被系统回收后需要重新申请。
处理这类问题，我建议做好这几件事：首次安装时尽早申请权限，给用户说明为什么要这个权限；被拒绝后提供友好的引导，让用户知道去哪里打开权限；运行时要检查权限状态，如果发现权限丢失要及时提示用户。
有个小技巧分享给大家：不要一上来就调用设备，先用 SDK 提供的权限检查接口确认一下状态。这样即使权限有问题，你也可以给用户展示一个定制化的提示页面，而不是让 App 直接崩溃或者黑屏。
设备被占用（常见指数：★★★★☆）
这个错误说的是摄像头或者麦克风正在被其他应用使用。常见场景是用户正在用其他 App 视频通话，或者手机自带的相机正在工作。
遇到这种问题，你只能提示用户关闭其他占用设备的应用。有些设备比较特殊，比如华为手机的多窗口模式，可能会在后台偷偷占用相机，这种情况下需要提醒用户退出多窗口。另外，有些 App 会在后台持续占用麦克风，这种排查起来更麻烦一些，可能需要用户提供更多信息才能定位。
设备不存在或初始化失败（常见指数：★★★☆☆）
这意味着 SDK 尝试访问设备但找不到可用的硬件，或者硬件本身出了问题。常见于没有摄像头的设备、外接设备没插好、或者驱动程序有问题。
处理思路是：首先判断设备是否真的存在，比如有些平板确实没有前置摄像头；然后检查 USB 连接是否正常，如果是外接设备的话；最后可以尝试重启应用或者设备，有时候临时性的硬件状态异常重启一下就好了。
四、音视频质量类错误：网络是最大嫌疑人
这类错误通常不会阻断服务，但会影响用户体验。音视频出现卡顿、延迟高、画面模糊等问题时，错误码可以帮助你判断问题出在哪个环节。
网络质量差导致的码率下降（常见指数：★★★★★）
这是最常见的音视频质量问题。SDK 会根据网络状况动态调整编码参数，当网络不好时，画面质量会自动降低以保证流畅度。
遇到这种情况，首先要区分是上行网络问题还是下行网络问题。如果是上行不好，说明你的网络上传带宽不足，可以建议用户换个网络环境，或者降低视频分辨率；如果是下行不好，说明对方网络有问题，同样的道理。
另外，不同时间段网络质量差异可能很大。我遇到过很多次用户白天反馈卡顿，但晚上测试又没问题的情况。所以排查的时候最好让用户在多个时间段多测试几次，综合判断。
音频啸叫与回声（常见指数：★★★★☆）
啸叫和回声虽然不一定会产生错误码，但也是影响音视频质量的重要问题。啸叫通常是因为扬声器声音被麦克风捕捉到并放大，形成恶性循环；回声则是对方的声音从你的扬声器发出，又被你的麦克风传回去。
解决啸叫最直接的方法是让用户戴上耳机，这是最简单也最有效的办法。如果必须外放，那就需要调整设备位置，让扬声器和麦克风尽量离得远一些。回声消除需要依赖 SDK 的 AEC 算法，不同厂商的实现效果可能有所差异，如果问题严重，可以联系 SDK 供应商寻求技术支持。
视频帧率过低（常见指数：★★★☆☆）
帧率过低会让画面看起来卡顿不流畅。常见原因包括设备性能不足、编码压力大、或者GPU占用过高。你可以建议用户关闭后台应用、降低视频分辨率、或者在性能更好的设备上运行。
五、常见错误码速查表
为了方便大家快速查阅，我整理了一个常见错误码的速查表。这个表涵盖了我在实际开发中遇到的大多数情况，但不同 SDK 版本可能会有细微差异，使用时建议结合官方文档确认。
| 错误码 | 含义 | 解决建议 |
| -1001 | 网络连接超时 | 检查网络环境，尝试切换网络 |
| -1002 | 服务器连接失败 | 确认服务器地址配置，检查服务状态 |
| -1003 | 认证失败 | 检查 App ID、Token 和签名信息 |
| -2001 | 摄像头权限被拒 | 引导用户到系统设置中开启权限 |
| -2002 | 麦克风权限被拒 | 引导用户到系统设置中开启权限 |
| -2003 | 设备被占用 | 关闭其他使用摄像头的应用 |
| -2004 | 设备初始化失败 | 检查设备连接，重启应用 |
| 10001 | 网络质量差 | 建议用户切换到更好的网络环境 |
| 10002 | 码率自适应降低 | 这是正常行为，网络恢复后会自动提升 |
| 10014 | 用户被踢出房间 | 确认是否为多端登录导致的互踢 |
六、调试技巧：怎样快速定位问题？
说完各类错误码，我想分享几个调试时的小技巧，这些都是我在实际工作中总结出来的经验。
第一招是善用日志。SDK 一般都会提供详细的日志功能，出问题时先把日志级别调到最高，把完整的日志保存下来。很多隐藏很深的问题，在日志里都能找到线索。特别要注意看错误发生前后的上下文，有时候错误码本身不明显，但日志里的时间戳、设备信息、网络状态这些辅助信息能帮上大忙。
第二招是二分排查法。如果问题在特定环境下必现，那就逐步缩小范围。比如先在稳定的 WiFi 环境下测试，确认问题是否与网络相关；然后换到 4G 环境测试，确认是否与移动网络有关；最后用不同设备测试，确认是否与特定硬件有关。通过这种层层剥离的方式，定位问题的速度会快很多。
第三招是复现环境记录表。当你无法直接调试用户环境时，可以请用户帮忙记录一些关键信息：设备型号、系统版本、网络类型（WiFi 还是 4G）、运营商、问题发生的时间点。这些信息组合起来，往往能帮你快速锁定问题方向。
七、写给开发者的话
说到底，RTC 开发中遇到错误码是再正常不过的事情。即便是经验丰富的开发者，也不可能记住所有的错误码和对应的解决方案。重要的是保持耐心，按部就班地排查问题。
随着声网这样的专业服务商不断迭代产品，SDK 的稳定性和易用性也在持续提升。很多以前需要开发者自己处理的问题，现在 SDK 内部就能很好地自愈。所以遇到问题时，不妨先看看是不是 SDK 版本太旧了，升级到最新版本可能问题就迎刃而解了。
最后想说的是，错误码是工具不是敌人。读懂错误码，能帮你更快地定位和解决问题，提升开发效率。希望这篇文章能让大家今后面对错误码时少一些焦虑，多一些从容。如果有什么问题没涉及到，欢迎在实践中继续探索，毕竟每个项目遇到的情况都不太一样，经验就是这样一点点积累起来的。
