当 Connection API 返回 errorCode 时使用本参考。阅读其 errorDescription 以了解具体失败。操作、响应位置和连接状态有助于确定下一步。
对于没有 API 错误的症状(例如已连接但视频不播放),请从故障排除开始。
顶层错误适用于整个请求。它并不一定表示操作没有做任何更改。例如,带协商的轨道关闭可能在 SDP 交换失败前已经关闭轨道。批量操作也可能在各个 tracks 或 dataChannels 结果中返回错误。检查每一项并保留成功的分配,即使另一项失败。
轨道和 DataChannel 批量操作可以返回带失败项的 HTTP 200。WebSocket 适配器的创建和关闭在至少一项成功时返回 HTTP 200,当所有尝试项都失败时返回 503。更早的请求校验或认证可能改为返回顶层错误。
项会暴露 errorCode 和 errorDescription,没有单独的 HTTP 状态。因此适配器外层的 503 也可能包含需要先纠正再重试的配置错误。
以下表格覆盖常见公开代码。每个操作的响应结构见 API schema。
| 代码 | 含义和下一步 |
|---|---|
unauthorized |
SFU App Secret 未被接受。检查后端的 bearer 头,以及该密钥是否属于所选应用。重试前先纠正授权。 |
not_found |
未找到 SFU 应用。检查 App ID。对于新创建的应用,重试前遵循响应中的传播说明。此代码针对应用,而不是缺失的发布。 |
decoding_error |
请求无法解码或校验。检查 JSON 和字段类型。对于 datachannels/establish,此代码也可以描述传输设置失败。按本表后的说明检查其设置状态。 |
invalid_params |
字段、值、组合或请求限制无效。检查该操作的 schema 和说明。重试前先纠正请求。 |
payload_too_large |
tracks/new 或 /renegotiate 请求超过正文大小限制。在保留完整生成 SDP 和按会话排序的前提下减小请求大小。 |
发往 datachannels/establish 的有效 JSON 请求,在传输设置失败时仍可能收到 decoding_error。检查请求是否指向预期会话,以及 DataChannel 传输是否已经协商。在下一次变更前完成任何未完成的 offer/answer 交换。不要把 establish 当作连接状态检查重复调用。
新连接使用完整消息配方,或向现有媒体连接添加 DataChannels。
| 代码 | 含义和下一步 |
|---|---|
session_error |
对于 HTTP 425,请完成连接设置。如果 PeerConnection 失败或已关闭,请改为创建新会话。对于 HTTP 410,请创建新会话并重新连接。 |
invalid_session_description |
SDP 无法被接受,或 offer/answer 顺序错误。检查生成的 SDP、transceiver、mid 值、编解码器支持,以及哪个会话期望 answer。完成未完成的交换,并串行化后续变更。交换结束后不要重放 answer。 |
仅有 HTTP 406 并不能说明请求发生了重叠。检查公开错误和端点状态。协商和会话生命周期说明完整交换边界和并发处理程序。
这些代码通常出现在各个资源结果中。有些操作也可能让整个请求失败。
| 代码 | 含义和下一步 |
|---|---|
not_found_track_error |
找不到请求的媒体发布或 DataChannel。对照应用发现检查其发布者会话 ID 和名称,并确认发布者已连接。对于媒体,检查它是否正在发送数据包。源可用后再重试。 |
empty_track_error |
媒体订阅未及时收到源媒体。检查发布者的连接和出站数据包,等媒体可用后再重试失败的订阅。 |
repeated_local_track_error |
DataChannel 分配已存在。此代码可适用于发布或订阅。核对已保留的分配。若意图是替换,先关闭正确的分配再重新创建。 |
update_track_error |
该轨道未配置为所请求的 simulcast 更新。检查发布,并对适用的接收轨道使用 simulcast 更新。 |
close_track_error |
轨道或 DataChannel 不存在或已关闭。对于应用拥有的资源清理,明确报告缺失即可满足该资源的清理。独立处理其他项。 |
simulcast 更新使用接收会话的 mid。媒体关闭使用你正在关闭轨道的那个会话上的 mid。DataChannel 关闭使用该端点已分配的通道 ID。参见标识符所有权和清理状态。
把每个媒体关闭结果与你修改的会话上所请求的 mid 匹配。例如,强制关闭 mid 0、1 和 2 可能返回 HTTP 200,内容为:
{
"requiresImmediateRenegotiation": false,
"tracks": [
{ "mid": "0" },
{
"mid": "1",
"errorCode": "close_track_error",
"errorDescription": "Track doesn't exist or was already closed"
},
{
"mid": "2",
"errorCode": "internal_error",
"errorDescription": "Backend error"
}
]
}轨道 0 已关闭。轨道 1 不存在或已关闭。将 2 和任何未报告的 mid 保持为待处理。对于 DataChannels,按 id 匹配结果。
没有项结果的请求级错误并不能证明资源不存在。中断的请求后遵循恢复和拆除指南。
这些代码出现在适配器操作的 tracks 结果中。外层 HTTP 状态反映批次结果。
| 代码 | 含义和下一步 |
|---|---|
websocket_localhost_not_allowed |
端点名为 localhost。提供可公开访问的 WebSocket 端点。重试同一地址无法让 SFU 访问到它。 |
websocket_handshake_failed |
端点未完成 WebSocket 升级。重试失败项前检查其 WebSocket 路由、升级响应和认证行为。 |
websocket_connection_timeout |
WebSocket 握手超时。检查端点可用性、路由和握手处理。提供最终端点 URL,因为适配器不会跟随重定向。 |
已经关闭的适配器计为成功关闭。保留失败的关闭项以便重试。示例见适配器关闭结果。
端点配置、数据包格式和恢复请遵循 WebSocket 适配器参考。
| 代码 | 含义和下一步 |
|---|---|
retryable_transient_error |
API 明确标识了可重试失败。通过会话的排序机制,用有界退避重试失败操作。保留其他操作的成功结果。 |
temporarily_unavailable_error |
服务暂时不可用。再次尝试前先等待。保留成功的分配,并在重复创建资源前核对不确定的变更结果。 |
transport_unavailable_error |
媒体传输设置未能完成。稍后尝试可能成功。限制重试次数,并在继续前检查会话是否仍可用。 |
backend_error |
服务无法获得或提供所需结果。保留资源状态和已脱敏的诊断上下文。在开始另一次变更前检查未解决的操作。 |
internal_error |
API 无法更具体地分类该失败。检查操作输入和当前会话/资源状态。保留诊断信息和未完成的清理。此代码并不规定自动重建资源。 |
逐项重试失败项,而不是重复整个部分成功的创建批次。没有响应的超时会使结果不确定。遵循重试和重连指南,并对持续失败保留诊断上下文。