错误码

C 接口用返回值表达结果。返回 int 的接口统一使用下面 5 个取值，RTC_OK 为 0，失败一律为负数。

#define RTC_OK              0   // 成功
#define RTC_ERROR          -1   // 一般错误
#define RTC_INVALID_PARAM  -2   // 参数无效
#define RTC_NOT_CONNECTED  -3   // 未连接
#define RTC_TIMEOUT        -4   // 超时

取值说明

常量	值	含义	常见原因与排查方向
`RTC_OK`	`0`	成功	——
`RTC_ERROR`	`-1`	一般错误	服务端拒绝、底层协商失败、Token 会话失效、身份不满足要求（如非 `__mcu__` 身份发布合成流）。开 DEBUG 日志看具体原因
`RTC_INVALID_PARAM`	`-2`	参数无效	实例/轨道句柄无效或已销毁、必填指针传了 `NULL`、Token 为空串、对非视频轨道请求关键帧
`RTC_NOT_CONNECTED`	`-3`	未连接	还没成功加入频道就调了需要连接的接口；`rtc_get_connection_quality` 下还表示”尚未收到第一帧质量数据”
`RTC_TIMEOUT`	`-4`	超时	仅 `rtc_join_channel_sync` 返回。Token 过期、网络不通、服务端不可达

RTC_ERROR 是一个笼统的失败码。具体原因用 rtc_get_last_error 取（0.0.9 起），它返回的就是下面两节的 180xxx / 1xxx 错误码。也可以调高日志级别看原因：

rtc_set_log_level(RTC_LOG_DEBUG);

日志里会打出更具体的错误，形如 180001: Not in channel 或 1021: ...。这两类码的区别见下面两节。

日志里的 `180xxx`：SDK 层错误

C 接口的这 5 个返回值只描述”调用层面”的结果，不携带原因。原因用 rtc_get_last_error 取，也会打在日志里，其中以 180 开头的 6 位码是 SDK 自身产生的错误：180 是服务端 / 嵌入式这种接入方式的前缀，后三位是具体错误，各端 SDK 的后三位统一（编号规则见错误码规则）。SDK 自身错误的原因是英文，请按错误码判断，不要按文案判断。

0.1.0 起错误码全面重排（如”无权发布合成流”由 180004 改为 180040，180004 改为表示 Token 不合法），下表按 0.1.0 及以后的版本列出。旧码与新码的对照见更新日志 · 0.1.0。

码	含义	常见原因
`180000`	未分类错误	兜底码，正常不应出现，看原因文案与日志上下文
`180001`	不在频道内	还没加入频道（或已离开）就调了会中接口；`RTC_NOT_CONNECTED` 对应此码
`180002`	Token 已过期	Token 超时未使用，或已被别的会话用掉
`180003`	流轨道不存在	目标 uid / trackId / desc 写错，或对方尚未发布该轨道
`180004`	Token 不合法	Token 解析失败或内容不完整，检查是否完整拷贝、是否为本环境签发
`180006`	连接失败	网络请求失败或 HTTP 非 200，检查网络与服务地址。SDK 在重连时会自动重试
`180007`	连接超时	`rtc_join_channel_sync` 在 `timeout_ms` 内未完成
`180009` / `180010`	信令连接失败 / 信令订阅失败	信令服务不可达，检查网络与防火墙
`180011`	响应解析失败	服务端返回的内容无法解析，多为服务地址指向了错误的服务或中间有代理改写
`180012`	底层 WebRTC 错误	如数据通道创建失败
`180013`	SDP 协商失败	媒体协商未通过
`180014`	传输未就绪	频道正在重连、流媒体引擎未连接，稍后重试即可
`180015`	媒体连接失败	媒体连接创建失败或已断开，检查 UDP 端口是否放通
`180019`	编解码器不支持	`rtc_create_local_track` 传了不支持的 codec
`180020`	超过发布上限	已发布的音频 / 视频轨道数达到上限
`180023`	流媒体引擎已关闭	等待过程中离开了频道或连接已断开
`180024`	当前状态不允许该操作	调用顺序不对，如轨道未就绪、引擎未初始化
`180025`	SDK 内部错误	如创建轨道失败、内存不足。请带上日志联系我们
`180026`	操作被取消	调用过程中离开了频道或销毁了实例
`180031`	参数非法	必填参数为空、视频轨道未设宽高帧率、轨道类型不符等；`RTC_INVALID_PARAM` 对应此码
`180032`	当前引擎不支持该能力	如当前流媒体引擎不支持切层
`180034`	超过订阅上限	已订阅的音频 / 视频轨道数达到上限
`180035`	发布描述冲突	同一个流槽位已被其它轨道占用，换一个 `desc` 或先取消发布
`180040`	无权发布合成流	发布 MCU 合成流要求以 `__mcu__` / `__amcu__` 身份接入，普通身份会被拒
`180204`	频道内没有该用户	目标 uid 不在频道内
`180300`	发布失败	媒体协商未通过，或流媒体引擎已断开，检查网络与编码参数
`180301`	订阅失败	媒体协商未通过，或目标轨道已被取消发布
`180302`	发布协商超时	网络不通或服务端不可达
`180303`	订阅协商超时	同上
`180304`	订阅时轨道不存在	对方还没发布完。SDK 会自动退避重试，日志里偶发出现属正常，持续出现才需排查

看到 180002（Token 已过期）时先确认不是 Token 复用：每个进程都要单独签发。这一条和下面的服务端 1032 是同一类问题的两种表现。

日志里的 `1xxx` 等：服务端业务错误码

四位数（≥1000）的码来自服务端，是业务层面的拒绝原因，SDK 原样透传，例如：

服务端码	说明	在 C 侧的表现
`1021`	channel token 已被使用	`rtc_join_channel_sync` 返回 `RTC_ERROR`
`1032`	该会话不在线	`rtc_join_channel_sync` 返回 `RTC_ERROR`

完整清单见服务端 API · 错误码。发布 / 订阅被服务端拒绝时（如 1033 并发已达上限、1035 节点满载），0.1.0 起 rtc_get_last_error 返回服务端原码，不再包成 180300 / 180301。服务端错误原因文案的语言由 rtc_set_language 决定，不设置时跟随系统语言。

Token 与一次会话绑定，进程离开频道后该会话即失效。复用同一个 Token 起第二个进程会拿到 1032（在 C 侧表现为 RTC_ERROR）—— 每个进程都要单独签发 Token。

返回值检查建议

所有返回 int 的接口都应检查返回值。加入频道这类关键路径失败时必须走清理流程，避免句柄泄漏：

void* rtc = rtc_create();

int ret = rtc_join_channel_sync(rtc, token, 10000);
if (ret != RTC_OK) {
    char msg[256];
    int code = rtc_get_last_error(rtc, msg, sizeof(msg));   // 具体原因，如 1033 并发已达上限
    fprintf(stderr, "join failed: %d, code=%d %s\n", ret, code, msg);
    rtc_destroy(rtc);        // 失败也要销毁实例
    return -1;
}

rtc_create / rtc_create_local_track 返回的是指针，失败时为 NULL，判空即可。

概览

Web SDK

Android SDK

Windows SDK

Swift SDK（iOS/macOS）

iOS SDK

HarmonyOS SDK

C SDK（服务端/嵌入式）

Python SDK（服务端 AI）

服务端 API

取值说明

日志里的 `180xxx`：SDK 层错误

日志里的 `1xxx` 等：服务端业务错误码

返回值检查建议

​取值说明

​日志里的 180xxx：SDK 层错误

​日志里的 1xxx 等：服务端业务错误码

​返回值检查建议

取值说明

日志里的 `180xxx`：SDK 层错误

日志里的 `1xxx` 等：服务端业务错误码

返回值检查建议