错误与排查
服务端 SDK 错误
| 错误码 | 含义 | 检查项 |
|---|---|---|
SDK_CLIENT_NOT_CONFIGURED | 使用了未配置的课堂或白板侧 | 检查对应客户端配置 |
SDK_TOKEN_INPUT_INVALID | 本地签名参数无效 | appId、appSecret、用户/房间标识、TTL |
SDK_NETWORK_ERROR | 网络调用失败 | DNS、TLS、服务地址和连通性 |
SDK_TIMEOUT | 等待请求超时 | 判断服务端是否已经完成操作 |
SDK_INVALID_JSON | 返回体不是有效 JSON | 网关错误页、反向代理与路由 |
HTTP_<状态码> 或后台 errorCode | 服务端拒绝请求 | 结合 HTTP 状态与 traceId 定位 |
服务端 EduskitError 的 status、errorCode、traceId、path、source 可用于排查；Python 使用 snake_case 字段，Java 使用 getter，Go 使用导出字段。本地签名失败不产生 HTTP 请求，通常没有服务端 trace。
客户端错误
客户端使用五位数字模块错误码，与服务端 SDK 的 SDK_* 字符串不同：
| 范围 / 代码 | 模块或含义 |
|---|---|
10001 / 10003 / 10004 | 未初始化 / 参数错误 / 状态不允许 |
20001 / 20002 / 20003 | 课堂不存在 / 权限不足 / 后台或网络错误 |
20004 | 后台响应缺失当前 SDK 必需字段 |
20005 | 进课被中止 |
20006 / 20007 / 20008 | 尚未开课 / 已结课 / 已过期 |
30001 / 40001 / 50001 / 60001 | IM / 白板 / RTC / 直播 Provider 错误 |
70001 | UI 资源错误 |
80001 / 80002 / 80003 | Provider 未注册 / 平台 Provider 失败 / 功能未实现 |
90001 | 内部未知错误 |
按阶段定位
- 安装或构建失败：确认包坐标、架构、native 绑定版本与 WASM 静态资源。
- 注册/建课失败：使用 server-api 地址，检查凭据及
durationMinutes；排课至少留出 10 分钟。 - join 401/403：检查 Token audience、过期时间、应用/环境、用户注册及成员名单。
- join 返回但未就绪：检查 IM 地址可达、登录与群确认；不要把 HTTP 返回当作进课成功。
- 白板或音视频单独失败：看
onJoinProgress对应域，再检查系统权限、供应商凭证、资源和网络。 - 设备图标与实际不符：按
onStreamInfoChanged更新，检查是否只根据命令回执更新了界面。
记录发生时间、SDK 版本、平台、课堂 ID、用户 ID、阶段与错误码；跨服务问题保留 traceId，多次进课再按 session/attempt 区分。不记录 appSecret、完整 Token、UserSig 或签名下载 URL。