播放会话错误参考

读取错误响应#

播放会话错误会返回 HTTP 状态，以及机器可读的 code、requestId、retryable 和 contractVersion。验证失败时还会指出具体字段错误。记录请求 ID 和失败阶段，但不要记录凭据、DRM License Tokens、Challenge 或许可证二进制数据。

{
  "status": 400,
  "code": "playback_session_invalid",
  "title": "The playback session request is invalid.",
  "requestId": "your-request-correlation-id",
  "retryable": false,
  "contractVersion": 1
}

以下仅为错误响应示例片段。实际响应还可能包含问题详情 type、detail 及字段级 errors。

playback_authentication_required#

HTTP 401。缺少项目 API 客户端凭据，或凭据对当前请求无效。

检查服务器端凭据、所选环境和 license-tokens:create 权限。

playback_session_invalid#

HTTP 400。一个或多个请求字段未通过验证。

阅读错误信息，修正指出的字段，并确保策略与已发布的加密输出包一致。

playback_environment_not_found#

HTTP 404。找不到指定的播放环境。

使用目标环境的 UUID 及属于该环境的凭据。

playback_content_not_found#

HTTP 404。没有找到与请求匹配的已发布加密输出包及有效密钥集。

检查服务器确认的 Content ID、所选环境、发布状态及有效密钥集。

playback_manifest_not_found#

HTTP 404。所需的已注册 Manifest 不可用。

确认已发布的输出包含所选 DRM 所需的 Manifest 类型。

playback_blocked#

HTTP 403。当前生效的 DRM-X 黑名单规则阻止播放。

检查当前适用的访问规则。不要让播放器通过反复重试或其他方式绕过该规则。

concurrent_stream_limit_reached#

HTTP 403。已达到并发播放数上限。

释放已结束或已放弃的播放会话，并执行账户访问策略。

playback_session_rate_limited#

HTTP 429。会话接口请求频率已达到上限。

响应包含 Retry-After 时，遵循其等待时间。避免重复创建会话，并采用有次数和时间限制的退避重试。

区分 API 请求失败与播放器播放失败#

创建播放会话成功，并不代表媒体文件、编码格式、设备 DRM 能力和输出保护均已就绪。请用故障阶段对照表确定最先失败的环节。