# Playback session error reference

Identify playback session API errors, understand HTTP status and request IDs, and choose a safe recovery action.

Canonical: https://docs.drm-x.com/api-reference/errors
Updated: 2026-09-05

![Your backend decides access; DRM-X enforces the signed policy. Encrypted media and DRM licenses follow separate delivery paths.](https://docs.drm-x.com/assets/session-flow.svg)Your backend decides access; DRM-X enforces the signed policy. Encrypted media and DRM licenses follow separate delivery paths.

## Read the problem response[#](#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[#](#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[#](#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[#](#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[#](#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[#](#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[#](#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[#](#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[#](#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[#](#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](https://docs.drm-x.com/troubleshooting/playback) to identify the first failed stage.