跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

错误代码

最后更新 查看 MarkdownAgent 设置

当 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 和按会话排序的前提下减小请求大小。

DataChannel 传输设置错误

发往 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 并不能说明请求发生了重叠。检查公开错误和端点状态。协商和会话生命周期说明完整交换边界和并发处理程序。

轨道和 DataChannel 错误

这些代码通常出现在各个资源结果中。有些操作也可能让整个请求失败。

代码 含义和下一步
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 无法更具体地分类该失败。检查操作输入和当前会话/资源状态。保留诊断信息和未完成的清理。此代码并不规定自动重建资源。

逐项重试失败项,而不是重复整个部分成功的创建批次。没有响应的超时会使结果不确定。遵循重试和重连指南,并对持续失败保留诊断上下文。

这篇文档对您有帮助吗?