跳转到主要内容
SDK 抛出的错误统一是 SRTCError,它继承 Error,并额外带以下字段: toString() 输出 "{code}: {detail}",方便日志里一行同时拿到码和描述。 另有静态方法 SRTCError.isServerError(e: Object): boolean(1.1.0 起):e 是 SRTCError 且码在后端业务区间 1000–99999 时返回 true。用它区分「后端业务错误(不必重试)」与「网络 / 解码失败(可重试)」——不要写成 e instanceof SRTCError,108006 / 108011 也是 SRTCError。
自 1.1.0 起错误码按跨端统一错误码表(第 2 版)重排:新增 031–301 若干码,网络 / HTTP 失败不再拼出 108404 / 108500,采集异常不再直接抛系统 BusinessError。1.0.1 及以前的旧码与新码对照见更新日志。下表「版本」列标注了各码的生效版本。

错误码是怎么拼出来的

  • SDK 内部错误:原始码 < 1000,会被加上平台前缀拼成 6 位数。 HarmonyOS 的 RTC 前缀是 108,所以内部错误码形如 108001、108231。
  • 业务后端透传的错误码:1000–99999 原样保留,不再加前缀。
  • HTTP 状态码不会拼进错误码(1.1.0 起):网络失败 / HTTP 非 200 一律 108006,HTTP 状态只在 httpStatus 与 detail 里。
这套编号与其它端一致(windows=101、android=102、iOS=103、linux=104、macOS=105、 web=106、小程序=107、HarmonyOS=108),同一类错误在各端的低 3 位相同, 跨端排障或统一做用户提示时直接比 baseCode。
code 与 kind 不是一一对应的。 HTTP API 请求失败的 kind 一律是 apiRequestFailed,code 按原因区分:
  • 后端返回业务错误:code 为后端码(≥ 1000,原样透出)
  • 网络失败 / HTTP 非 200,或后端返回了 < 1000 的异常码:108006(HTTP 状态见 httpStatus)
  • 响应不是 JSON、缺 code 字段或缺必需字段:108011
所以按 kind 分支时,apiRequestFailed 里还要再看 code。

报错语言

  • detail 一律英文,给开发者和日志看,会随版本调整;不要拿它做分支判断,也不要直接展示给终端用户,请按 code / baseCode 自行映射提示文案。
  • SRTC.setLanguage(lang)(1.1.0 起,缺省跟随系统语言)决定请求后端时的 Accept-Language 头,后端业务错误(1000–99999)的文案随之返回中文或英文;SDK 自身报错不受它影响。

连接相关


信令相关


WebRTC / 传输相关


轨道与采集相关

采集失败一律是 SRTCError(1.1.0 起)。 此前采集失败直接抛系统 BusinessError 或空 Error;现在统一包装,原 BusinessError.code 放 systemCode、原异常放 cause。以前按 e.code === 201 判断无权限的代码,改为判断 kind(cameraPermissionDenied / micPermissionDenied)。摄像头 / 麦克风的 108231 / 108251 主要来自采集前的只读权限预检:SDK 不申请权限、不弹授权框,权限由宿主申请,见集成方式。
108039 目前只覆盖系统码 201。 用户在屏幕共享授权窗点「取消」时,系统实际抛出的码尚待确认,可能落到 108018。需要区分「用户取消」时请结合 systemCode 判断。

频道成员相关


流媒体(发布 / 订阅)相关

引擎正在重连时发布 / 订阅报的是 108014(稍后可重试),不是 108300 / 108301。

引擎与通用错误

108027–108030 在统一码表里是虚拟背景相关码,鸿蒙 SDK 不使用。

推荐的处理方式

JSON.stringify(new Error()) 的结果是 {}。ArkTS 里直接把错误对象序列化进日志会得到一个空对象,什么线索都没有。排障时请显式取 code / detail(SDK 错误)或 code / message(系统 BusinessError)。1.1.0 起采集失败已包成 SRTCError,系统原码在 systemCode。
建议在业务层把 SRTCError 映射成你们自己的错误域,而不是把英文 detail 直接展示给最终用户。

编解码相关的坑

codecNotSupported 不一定会抛出来 —— 更常见的情况是「静默降级」。@ohos/webrtc 的 H264 / H265 是纯硬编,没有软编兜底。当设备能力表里查不到 H264 时, SDK 内部会跳过编码偏好设置、退回默认顺序(通常是 VP8),这个过程不报错。表现是本机看得到画面,但与 Web / iOS / Android / CDN 互通不上。所以自测不能以 “看到画面”为准,要核对实际协商到的编码格式:
videoCodecReport() 会把收发两个方向的能力连同 sdpFmtpLine 一起列出来, 用它确认发送侧有没有 video/H264。只有接收侧有是不够的 —— 收得下不代表发得出。