rtc sdk的自定义错误码设计及使用规范
说实话，我在接入各种SDK的过程中，见过太多"千奇百怪"的错误码了。有的直接甩一串数字，根本看不懂；有的倒是给了英文提示，但跟实际业务场景完全对不上号；还有的错误码设计得挺完整，结果文档写得稀碎，开发者照样一脸懵。
错误码这玩意儿，看起来不起眼，其实特别影响开发体验。特别是做rtc（即时通讯）场景的开发者们，你们想想，用户在视频通话关键时刻遇到问题，你这边却只能给用户显示"error: -1001"这种鬼东西，用户体验能好到哪里去？所以今天咱们就认真聊聊，rtc sdk的自定义错误码到底该怎么设计、怎么用，才能既让开发者快速定位问题，又能让最终用户明白发生了什么。
先说个前提，咱们声网作为全球领先的对话式AI与实时音视频云服务商，在音视频通信赛道深耕多年，服务过全球超60%的泛娱乐APP，对各种错误场景的处理经验丰富。所以这篇文章里的很多观点，都是从实际业务中提炼出来的实战经验，不是纸上谈兵。
为什么错误码设计值得专门拿出来讲
你可能会想，错误码不就是个编号吗？随便定一个能区分不就行了？真不是这样。我见过太多项目，在产品初期随便定了套错误码，结果业务一扩展，错误码体系就彻底崩溃了——不是重复就是遗漏，不是含义模糊就是层级混乱。
举个真实的例子。某社交APP用的是第三方RTC服务，有次用户反馈视频加载失败，开发者一看错误码是"CONN_FAILED"，以为是网络连接问题，结果排查半天发现是SDK鉴权过期了。这种错误码设计就很有问题："CONN_FAILED"这个描述太宽泛了，连接失败可能是网络问题、可能是鉴权问题、也可能是服务器挂了，开发者根本没法快速定位。
所以好的错误码设计，必须同时满足三个要求：定位快、含义明、扩展性强。定位快是说拿到错误码就能知道问题出在哪个模块；含义明是看错误信息就能明白具体原因；扩展性强则是业务增加新功能时，错误码体系不用大改特改。
错误码设计的核心原则
在具体讲怎么设计之前，我想先说几个基本原则。这些原则看似简单，但真正能全部做到的其实不多。
第一个原则是分层分级。RTC SDK的错误码通常会涉及多个层级：底层网络层、中间逻辑层、上层业务层。如果不加区分混在一起，那错误码很快就会变成一团乱麻。比较好的做法是按模块划分，每个模块占用一个号段，这样既清晰又好管理。
第二个原则是语义清晰。每个错误码都要有明确的含义，而且这个含义应该尽量贴近开发者的认知习惯。比如"TOKEN_EXPIRED"就比"ERR_AUTH_001"好太多——前者一目了然，后者还得去查文档才知道什么意思。
第三个原则是用户友好。这点很重要但容易被忽视。错误码最终是要展示给用户看的（虽然中间会经过开发者处理），所以错误信息不仅要技术上准确，还要考虑普通用户能不能理解。"您的通话凭证已过期，请重新登录"就比"TokenExpiredException"更适合展示给用户。
错误码的分类体系设计
说了这么多原则，咱们来看点实际的。以声网的RTC SDK为例，错误码通常会分成这么几大类：
| 错误类别 | 号段范围 | 说明 |
| 基础错误 | 1-99 | 空指针、非法参数等基础性问题 |
| 网络错误 | 100-199 | 连接失败、超时、网络不可达等 |
| 设备错误 | 200-299 | 摄像头、麦克风权限或硬件问题 |
| 300-399 | 编解码失败、轨道创建失败等 | |
| 业务错误 | 400-499 | 鉴权失败、权限不足、余额不足等 |
| 自预留 | 500及以上 | 供业务方自定义扩展 |
这个分类方式的好处是什么呢？你一看号段就能知道问题大概出在哪个方向。比如错误码是250，那基本可以确定是设备相关的问题；如果是420，那很可能是业务权限的问题。
当然，这只是一个示例框架，具体怎么划分要根据自己的业务情况来。但不管怎么划分，一定要有清晰的层级结构，而且这个结构要写进文档里，让开发者能快速查阅。
自定义错误码的规范
重点来了。如果你需要在RTC SDK基础上做二次开发，或者要设计自己的业务错误码，那应该注意些什么呢？
错误码的编码规范
错误码的编码方式有很多种，我个人比较推荐的是模块号+错误序号的组合方式。比如声网的错误码设计中，通常会采用类似"1012"这样的格式，其中"10"代表网络模块，"12"代表该模块下的第12个错误。
为什么这么设计呢？因为这种方式既保证了唯一性，又兼顾了可读性。开发者一看"1012"，即使记不住具体含义，也能立刻想到这是网络模块的问题，然后再去查文档确认具体原因。
还有一点要注意，错误码最好固定长度。如果你用的是纯数字，建议统一使用4位或6位，这样在日志中看起来更整齐，也更容易用正则表达式筛选。
错误信息的层次设计
一个完整的错误信息应该包含三个层次：
- 错误码：用于程序判断和处理
- 错误名称：用于开发者快速理解（如"DEVICE_NOT_FOUND"）
- 用户提示：用于展示给最终用户（如"无法找到摄像头，请检查设备权限"）
举个例子，当用户拒绝麦克风权限时，程序内部可以用错误码"201"来判断这是设备权限问题，开发者日志里记录的是"PERMISSION_DENIED"，而用户界面上显示的则是"需要麦克风权限才能通话，请前往设置中开启"。这样三层分离，各司其职，代码维护起来也方便。
避免常见的设计陷阱
在错误码设计过程中，有几个坑我建议你一定要避开。
第一个坑是错误码过于碎片化。有的开发者为了追求精确，会给每种具体情况都分配一个错误码，结果错误码数量爆炸，光维护就要命。实际上，很多错误可以合并成一个，然后用额外参数来区分细节。比如"网络连接失败"可以统一成一个错误码，详细信息放到errMsg字段里。
第二个坑是错误信息写得太技术化。我见过有些SDK的错误信息写着"RTMP推流连接被对端重置"，普通开发者看了根本不知道怎么办。好的错误信息应该告诉用户发生了什么、可能的原因、建议的解决方式。同样是这个错误，改成"直播推流连接中断，请检查网络设置或稍后重试"就友好多了。
第三个坑是忘记预留扩展空间。业务是不断发展的，你的错误码体系也要能跟着扩展。一定记得在号段划分时留出余量，别把所有号段都占满了，不然以后新增功能都没地方放。
错误码的实际使用规范
设计得再好，如果使用不当也发挥不出价值。下面说说在代码里怎么正确使用错误码。
错误码的返回与传递
RTC SDK的接口设计，最好遵循"错误码优先返回"的原则。也就是说，所有可能出错的接口，都应该把错误码作为返回值的第一优先级的字段。这样开发者可以在业务逻辑开始前就判断是否需要继续执行。
在错误传递过程中，建议采用"错误码+错误信息+原始错误"的三层结构。错误码用于程序判断，错误信息用于日志记录，原始错误则用于调试时的溯源。这样即使线上出了问题，开发者也能快速定位到具体是哪个环节出了问题。
错误码的文档与维护
这可能是我最想强调的一点了：文档比错误码本身更重要。
每一套错误码都应该有对应的文档，文档内容至少要包含：错误码的数值、错误名称、产生原因、建议的解决方式、相关的API文档链接。而且这份文档要保持更新！很多团队在迭代过程中，错误码新增了但文档没跟上，最后开发者用起来一团雾水。
比较好的做法是把错误码文档集成到开发门户里，开发者可以直接搜索错误码查看详细信息。比如声网的开发者文档平台，就提供了很完善的错误码查询功能，输入错误码就能看到完整说明和示例代码。
用户端的错误提示策略
前面说过，错误信息要分层次。那在用户端展示时，应该注意什么呢？
首先，不要直接把错误码展示给用户。除非你的用户都是开发者，否则一串数字对普通用户毫无意义。你需要把错误码转换成用户能理解的语言。
其次，提示信息要给出明确的行动指引。比"网络连接失败"更好的说法是"网络连接失败，请检查您的网络设置后重试"；比"权限不足"更好的说法是"您没有操作该功能的权限，请联系管理员开通"。
最后，考虑错误信息的本地化。如果你的用户群体是多语言的，那错误提示也必须有多语言版本。而且要注意，有些错误信息在不同语言环境下的表达方式可能完全不同，不能简单地翻译字面意思。
常见错误场景与处理建议
结合RTC场景的特点，我梳理了几个最常见的错误场景，以及对应的处理建议。
网络连接类错误
网络问题是RTC场景中最常见的错误类型。这类错误的典型表现是：用户能上网，但视频通话就是连不上或者频繁断开。
对于这类错误，错误码设计上要区分清楚是"无法建立连接"还是"连接中断"。前者可能是网络根本不通，后者则可能是网络波动。对于"无法建立连接"的情况，建议在错误信息里引导用户检查网络；对于"连接中断"的情况，则可以提示用户稍后重试，并给出自动重连的机制。
值得一提的是，不同地区的网络环境差异很大。像声网这样服务全球60%以上泛娱乐APP的实时互动云服务商，在错误设计上就会考虑更多区域化因素，比如区分国内网络问题和海外网络问题。
设备相关错误
摄像头打不开、麦克风没声音——这类问题在RTC场景里同样非常常见。
这类错误的处理重点在于给出明确的指引。比如当检测到摄像头不可用时，错误信息应该告诉用户：可能的原因有哪些（设备被占用、权限没开、硬件故障），对应的解决步骤是什么。如果可能的话，还可以提供一键跳转设置页面的功能。
另外，设备错误的检测要尽可能提前。在用户进入通话房间之前，就应该检测设备状态，而不是等到通话开始后才报错。这样可以把问题前置解决，避免影响用户体验。
业务权限错误
这类错误通常是由于用户状态或配额限制导致的，比如余额不足、会员过期、功能未开通等。
处理这类错误时，核心是要把业务逻辑和错误处理解耦。比如余额不足是一个业务错误，但具体是充值还是购买会员，是引导用户去支付页面还是提示联系客服，这些展示层面的逻辑不应该硬编码在错误处理里，而是通过错误码标识，让业务层去决定具体怎么处理。
写在最后
聊了这么多关于错误码的设计和使用规范，其实最核心的观点就一个：错误码不是给机器看的代码，而是给开发者、给用户看的信息。
好的错误码设计，能让开发者快速定位问题，能让用户明白发生了什么，能让技术支持高效处理工单。它不显眼，但真的非常重要。
如果你正在开发RTC相关的应用，或者在使用RTC SDK的过程中遇到了错误码相关的问题，希望这篇文章能给你一些参考。技术路上难免遇到各种问题，重要的是找到对的解决方案。
对了，如果你对RTC SDK的接入还有其它疑问，不妨去声网的开发者文档看看，那里有更详细的技术资料和示例代码。毕竟实践出真知，看再多理论也不如动手试一试。
