Skip to main content

Error codes

info

The library follows a hexadecimal error system. The least significant 16-bits (Bits 0-15) indicate a Component Error Code, and the most significant 16-bits (Bits 16-31) indicate the Categories that the error falls into.

Categories​

Error CategoryMaskDescription
Network Error0x10000Indicates that the error occurrence is network related.
Server Error0x20000Indicates a server response failure.
Thirdparty Error0x40000Indicates a failure in third-party components such as External Player, third-party Libraries.
Reserved0x80000Reserved for future use.
Reserved0x100000Reserved for future use.
Reserved0x200000Reserved for future use.
Playback Error0x400000Indicates that the error occurrence is during a Playback.
Download Error0x800000Indicates that the error occurrence is during a Download.
Interpretation of errors
  • 0x40* - Playback Error most probably due to the player itself.
  • 0x41* - Playback error due to Network failure.
  • 0x42* - Playback error due to Server response failure.
  • 0x80* - Download error most probably due to the downloader itself.
  • 0x81* - Download error due to Network failure.
  • 0x82* - Download error due to Server response failure.

Playback error code​

The following playback error codes are defined.

Error CodeHexadecimal valueComponent Error CodeDescription
MEDIA_SOURCE_FAILURE0x4002010x201Indicates that an error has occurred while loading the MediaSource.
MEDIA_SOURCE_TIMEOUT0x4002020x202Indicates that Fetching of the Media Source from network timed-out.
DRM_PROVISIONING_FAILURE0x4002030x203Indicates that an error has occurred while Provisioning Model Certificates on the specific device.
DRM_PROVISIONING_TIMEOUT0x4002040x204Indicates that Fetching of DRM Provisioning Data from Network Timed-Out.
DRM_LICENSE_FAILURE0x4002050x205Indicates that an error has occurred while Loading DRM Keys for a particular content either from network (or) persistent storage.
DRM_LICENSE_TIMEOUT0x4002060x206Indicates that Fetching of DRM Keys from network timed-out.
DRM_LICENSE_EXPIRED0x4002070x207Indicates that Loaded DRM Keys are expired.
MEDIA_PLAYBACK_FAILURE0x4002080x208Indicates that rendering of media failed.
MEDIA_PLAYBACK_STALE0x4002090x209Indicates Player playback has stalled.
DRM_KEY_REDUNDANT_REQUEST0x40020A0x20AIndicates the prefetch key already requested.
DRM_KEY_FETCH_INTERRUPTED0x40020B0x20BIndicate the license fetcher delegate not set.
SHARE_PLAY_ACTIVATION_FAILURE0x40020C0x20CIndicates SharePlay activation has failed.
PLAYBACK_NOT_ALLOWED_ON_INSECURE_DEVICE0x4002110x211Indicates the playback is not allowed due to device security thread.
PLAYBACK_NOT_SUPPORTED_ON_EXTERNAL_DISPLAY0x4002120x212Indicates the playback not supported on external display.
AIRPLAY_RECEIVER_TEMPORARILY_NOT_AVAILABLE0x4002130x213Indicates airplay receiver temporarily unavailable
MEDIA_SERVICES_WERE_RESET0x4002140x214Indicates that a daemon has crashed.
PLAYBACK_BUFFER_TIMEOUT0x4002150x215Indicates Indicates the player buffer timeout error.
AUDIO_SERVICE_FAILED0x4002160x216Indicates Audio Browser service failure for Audio Playback.
IMA_STREAM_MANAGER_INITIALIZATION_FAILURE0x4002170x217Indicates a failure when loading ads for IMA Server

Download error code​

The following download error codes are defined.

Error CodeHexadecimal valueComponent Error CodeDescription
DOWNLOAD_FAILURE0x8003010x301Indicates that an error has occured while downloading.
DOWNLOAD_TASK_NOT_FOUND0x8003020x302Indicates download task does not exists!
RETRY_FAILURE0x8003030x303Indicates the creating download task retry has failed.
DRM_PERSISTENCE_FETCH_NOT_POSSIBLE0x8003040x304Indicates successive key fetch within same session not possible due to limitations with ContentKeySession.
DOWNLOAD_TASK_METADATA_NOT_FOUND0x8003050x305Indicates that the task doesn't contain the necessary metadata to retry the download.

Specific error codes​

The following table provides details about specific error codes and their meanings.

Error CodeHexadecimal valueComponent Error CodeDescription
MEDIA_SOURCE_FAILURE0x4002010x201Indicates that an error has occurred while loading the MediaSource.
MEDIA_SOURCE_TIMEOUT0x4002020x202Indicates that Fetching of the Media Source from network timeout.
DRM_PROVISIONING_FAILURE0x4002030x203Indicates that an error has occurred while Provisioning Model Certificates on the specific device.
DRM_PROVISIONING_TIMEOUT0x4002040x204Indicates that Fetching of DRM Provisioning Data from Network timeout.
DRM_LICENSE_FAILURE0x4002050x205Indicates that an error has occurred while Loading DRM Keys for a particular content either from network (or) persistent storage.
DRM_LICENSE_TIMEOUT0x4002060x206Indicates that Fetching of DRM Keys from network timeout.
DRM_LICENSE_EXPIRED0x4002070x207Indicates that Loaded DRM Keys are expired.
MEDIA_PLAYBACK_FAILURE0x4002080x208Indicates that rendering of media failed.
MEDIA_PLAYBACK_STALE0x4002090x209Indicates Player playback has stalled.
OUT_OF_MEMORY_ERROR0x40020A0x20AIndicates that Player is Out Of Memory and is unable to allocate Resources.
DEVICE_FAILURE0x40020B0x20BIndicates that Device failed to handle the Media Content.
EXTERNAL_ABORT0x40020C0x20CIndicates that Playback was aborted by external sources because of Application specific Policy Restrictions.
INVALID_LIVE_MEDIA_SEGMENT0x40020D0x20DIndicates that Playback failed because of BehindLiveWindowException i.e. the playback is behind the allowed live window.
NETWORK_CONNECTION_FAILURE0x40020E0x20EIndicates that an error has occurred due to inactive network connection.
NETWORK_END_POINT_UNREACHABLE0x40020F0x20FIndicates that an error has occurred because of URL's domain is misspelled or does not exist, a socket timeout, the target host is unreachable or the server unexpectedly closes the connection even with active network connection.
PLAYBACK_BUFFER_TIMEOUT0x4002150x215Indicated that Buffering timeout has occurred.

MediaTailor error codes​

The following error codes are specific to MediaTailor.

Error CodeHexadecimal valueComponent Error CodeDescription
MEDIA_TAILOR_SESSION_API_FAILURE0x411010x1101Unable to return session data response from the network request
MEDIA_TAILOR_SESSION_DATA_PARSING_FAILURE0x411020x1102Session data parsing failed
MEDIA_TAILOR_TRACKING_API_FAILURE0x411030x1103Unable to return tracking data response from the network request
MEDIA_TAILOR_TRACKING_DATA_PARSING_FAILURE0x411040x1104Tracking data parsing failed.
MEDIA_TAILOR_TRACKING_API_MISSING0x411060x1106Tracking API missing in session data

Error object​

The Error object returned by the library is a linked list that traces the error occurrence from a higher-level component to the lower-level component where the error actually occurred.

Example

The Player component can talk to an internal component that in turn talks to a head-end server. If the server returns an error-ful response, the Error object returned from the player component might have the internalError property set to the error thrown by the internal component, which might actually be a server error information.

The deeper you go in the linked list, the more specific the Error is. You can utilize the depth of Error information as needed.

interface Error {
  /**
   * Unique Error Code with all Category Masking Set.
   */
  val errorCode: Int
  /**
   * Error message describing the Error.
   */
  val errorMessage: String
  /**
   * The internal root-cause of the Error if any.
   */
  val internalError: Error?
  /**
   * The internal Contextual description of the Error if any.
   * This is usually set if the error is from a third-party source.
   */
  val contextDescription: String?
  /**
   * A Computed property that returns the component error code
   * removing all CATEGORY MASK.
   */
  val componentErrorCode: Int
}

Player restart​

We recommend configuring the player to restart automatically when it encounters error PlayerErrorCodes.PLAYBACK_BUFFER_TIMEOUT to improve playback reliability.

 fun playerError(error: Error) {
    val errorCode = error.errorCode
    val hexErrorCode = error.hexErrorCode()
    if (error.hexErrorCode() == PlayerErrorCodes.PLAYBACK_BUFFER_TIMEOUT.toString()) {
        // Re-prepare the player (re-authorize and create a new player instance).
    }
}