Data resiliency

This guide explains the DIVA Web data resiliency behavior that is relevant for integrators.

Data resiliency means DIVA tries to keep playback available when a dependency fails, as long as the backend can provide a valid playable source or refreshed entitlement data.

In DIVA Web, the implemented resiliency workflows are:

Workstream	Purpose	Integrator perspective
WS5	Bypass entitlement for Business Continuity Plan (BCP) DRM-free sources	Use when Back Office (BO) publishes a valid DRM-free source with bypassEntitlement: true
WS6	Retry entitlement after eligible fatal playback errors	Use when entitlement may return a refreshed token, license URL, manifest URL, or backup endpoint

Standard retry handling

Standard retry handling is the first resiliency layer. It retries the same failed request using the configured retry policy.

This includes:

• Entitlement and heartbeat requests for HTTP 408 and 429
• Playback/network requests for HTTP 408, including manifests, media segments, video data, tracking URLs, and closed captions

If playback still fails after standard player/request retries are exhausted, WS6 may start for eligible fatal playback errors. WS6 is different because it sends a new entitlement request with Data.retries and may receive refreshed playback data or a backup endpoint.

How this relates to data resiliency:

Area	Category	Why
Entitlement 408 / 429 retry	Standard entitlement retry	Same entitlement request is retried using configured retry policy
Heartbeat 408 / 429 retry	Standard heartbeat retry	Same heartbeat request is retried using configured retry policy
Playback manifest 408 retry	Standard player/network retry	Player retries the same failed playback resource
Segment/chunk 408 retry	Standard player/network retry	Media engine retries the same failed media request
Video data 408 retry	Standard video data retry	BO/video metadata request retry, not entitlement failover
Tracking URL 408 retry	Standard metadata/tracking retry	Same request retry
WS6 Data.retries	Entitlement recovery after fatal playback error	Happens only after normal resource-level retries are exhausted and a fatal eligible player error reaches DIVA

WS5: BCP source with entitlement bypass

WS5 allows BO/video metadata to switch playback to a pre-authorized DRM-free BCP source.

Normal protected flow:

Video metadata -> Entitlement -> DRM playback

BCP bypass flow:

Video metadata -> bypassEntitlement: true -> Skip entitlement -> DRM-free playback

How WS5 works

1. BO returns source data.
2. The selected source contains bypassEntitlement: true.
3. DIVA maps this value into the normalized video source.
4. The source is treated as DRM-free.
5. DIVA does not add entitlement DRM parameters for that source.
6. DIVA skips the remote entitlement request.
7. DIVA creates a local entitlement success response using the source URI.
8. Playback starts with the provided manifest URL.

For bypass sources, DIVA returns an internal success shape equivalent to:

• contentUrl: source uri
• drmData.licenseUrl: empty string
• heartBeatInterval: 0
• payload: empty object

WS5 requirements

The integrator/backend must ensure:

• BO publishes bypassEntitlement: true for BCP sources.
• The BCP source URI is already playable.
• The BCP source is DRM-free.
• The app and backend have tested this path before an incident.
• Video polling can publish the BCP source when the active source needs to change.

Example source:

{
  "sources": [
    {
      "uri": "https://example.com/bcp/manifest.mpd",
      "format": "DASH",
      "name": "BCP-DASH",
      "bypassEntitlement": true
    }
  ]
}

Note: BO may expose the field as bypassentitlement, but DIVA Web source objects use bypassEntitlement.

WS6: Entitlement retry after fatal playback error

WS6 handles eligible fatal playback errors before DIVA shows the final playback error. DIVA asks entitlement again for refreshed playback details, then restarts playback with the returned data.

This can help when entitlement can return:

• A backup manifest URL
• A refreshed DRM token
• A refreshed license URL
• Updated DRM headers
• A healthier CDN/origin endpoint

WS6 is not a same-request network retry. Standard player/request retries happen first. WS6 starts only after the media player emits a fatal error that DIVA classifies as retryable.

WS6 configuration

{
  "settings": {
    "errorsHandling": {
      "entitlementRetriesOnPlaybackError": 3
    }
  }
}

Setting	Meaning
0	Disabled. This is the default.
> 0	Maximum number of entitlement recovery attempts.
Negative value	Normalized to 0.

How WS6 works

1. DIVA starts playback normally.
2. The initial entitlement request does not send Data.retries.
3. The player performs its normal internal/request-level retries.
4. If the player emits an eligible fatal error, DIVA intercepts it.
5. DIVA hides the final UI error while recovery is in progress.
6. DIVA increments the recovery attempt.
7. DIVA sends a new entitlement request with Data.retries.
8. Entitlement may return the same endpoint or a backup/refreshed endpoint.
9. DIVA updates the current source and DRM data.
10. DIVA rebuilds playback.
11. When playback reaches PLAYING, DIVA resets the retry counter.
12. If attempts are exhausted, DIVA surfaces the final playback error.

Data.retries is serialized as a string in the entitlement Data payload.

Example:

Request	Data.retries
Initial entitlement request	Not sent
First WS6 recovery request	"1"
Second WS6 recovery request	"2"
Third WS6 recovery request	"3"

Retryable WS6 failures

DIVA Web retries failures that may be fixed by refreshed entitlement data or a different endpoint:

• DRM player errors
• HTTP 408
• HTTP 500 through 599
• Timeout errors
• Browser network failures without a usable HTTP response, commonly status-0
• Some HLS status-0 load failures represented as source/load errors

DIVA Web does not retry every player error. For example:

• HDR capability errors 3015 and 3016 stay on the existing HDR fallback path.
• HTTP 429 is not part of the WS6 retry behavior.
• Non-retryable errors go directly to normal final error handling.
• Exhausted retry attempts surface the final playback error.

V2 and V3 entitlement API versioning

V2 and V3 are entitlement API versions. They are not resiliency workstreams.

DIVA Web can pass version intent into entitlement request data. In the current implementation, when the configured entitlement version is 3 or v3, DIVA adds:

{
  "version": "3"
}

to the entitlement Data payload.

Integrator responsibility:

• Confirm whether routing is handled by entitlement/backend services or by configuration.
• Avoid ad-hoc URL string replacement where possible.
• Prefer explicit environment/configuration-driven endpoint routing.
• Validate that V2/V3 requests reach the expected entitlement contract.

Which feature should I use?

Scenario	Recommended capability
BO can publish a DRM-free BCP source	WS5
Entitlement may return a refreshed or backup endpoint after playback failure	WS6
App needs to select entitlement API version	V2/V3 configuration
Manual DRM-to-non-DRM operational failover	Platform/operations BCP runbook, not only DIVA Web config

Validation checklist

Validate with controlled failure scenarios:

• BCP source with bypassEntitlement: true
• BCP source is played without entitlement call
• Normal source still performs entitlement
• Polling can switch from normal source to bypass source
• entitlementRetriesOnPlaybackError: 0 disables WS6
• WS6 sends no Data.retries on the initial request
• WS6 sends "1", "2", etc. during recovery
• Entitlement can return a backup URL/token/license
• Final error appears after retry exhaustion
• HTTP 408 and 5xx behavior is confirmed
• HTTP 429 is not treated as WS6 retryable
• V2/V3 routing reaches the expected entitlement API

Important boundaries

• WS5 is source-level entitlement bypass for DRM-free BCP playback.
• WS5 is not generic DRM error recovery.
• WS6 is entitlement retry after eligible fatal playback errors.
• WS6 is not the same as normal HTTP/player resource retries.
• Data.retries belongs to WS6 recovery entitlement requests.
• V2/V3 is API versioning, not data resiliency.
• WS7/WS8 should be described only as broader platform/operational capabilities unless their DIVA Web implementation and settings are confirmed.

Reference points

• Entitlement and DRM
• Settings: entitlementCheck
• Playback errors