Playback session error reference

Read the problem response#

Playback session errors include an HTTP status plus machine-readable code, requestId, retryable, and contractVersion. Validation failures also identify field errors. Record the request ID and failed stage without logging credentials, DRM License Tokens, challenges, or license bytes.

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

This is an illustrative error excerpt. Actual responses can include a problem type, detail, and field-specific errors.

playback_authentication_required#

HTTP 401. The project API client is missing or not valid for this request.

Check the server-side credentials, environment, and license-tokens:create scope.

playback_session_invalid#

HTTP 400. One or more request fields fail validation.

Read errors, fix the named fields, and match the policy to the published package.

playback_environment_not_found#

HTTP 404. The playback environment could not be found.

Use the intended environment UUID with its own credentials.

playback_content_not_found#

HTTP 404. No published package and active key set match this request.

Check the trusted Content ID, environment, published state, and active key set.

playback_manifest_not_found#

HTTP 404. The required registered manifest is unavailable.

Verify that the published output contains the manifest type required for this DRM.

playback_blocked#

HTTP 403. An active DRM-X blacklist rule blocks playback.

Review the applicable access rule. Do not retry or bypass it from the player.

concurrent_stream_limit_reached#

HTTP 403. The concurrent-stream limit has been reached.

Release finished or abandoned sessions and apply your account access policy.

playback_session_rate_limited#

HTTP 429. The session endpoint rate limit was reached.

Respect Retry-After when provided. Avoid duplicate session requests and use bounded backoff.

Separate API failures from playback failures#

A successful session response does not prove that media, codecs, DRM device support, or output protection are ready. Use the failure-stage matrix to identify the first failed stage.