The playbackError event in the playback namespace indicates playback errors on the group, such as a media server timing out, or when there’s no content loaded on the player.
Most playback errors occur when the player requests audio from the media server and the request fails. Your app can use the errorCode to handle specific types of errors, and log the reason string for debugging the error.
If a cloud queue is loaded as the audio source on a group, your app can also receive playbackError events on cloud queue server request errors. Your app will also receive the itemId of the cloud queue track that caused the error. Players communicate in the background with the cloud queue server to retrieve new tracks when needed. See Play audio for more details.
Parameters
See the Control documentation for descriptions of parameters in the header. See the table below for descriptions of parameters in the body.
| Parameter | Type | Value |
|---|---|---|
errorCode |
string | An error state. See the list below. |
httpStatus |
number | If the error was due to a server request, this field should be set to the HTTP status code from the server response. |
itemId |
string | The item ID of the current track, if the audio source is a cloud queue. |
queueVersion |
string | The last cloud queue change state identifier cached by the player. This could have been from:
This is omitted when the value is unknown, for example, if the server did not respond to a query. |
reason |
string | The reason for the error. This string is optional, so it may not always be returned. It is in English and not localized. Your app should only use it for debugging purposes. |
Error states
| Value | Definition |
|---|---|
ERROR_CLOUD_QUEUE_SERVER |
Indicates that a request to the cloud queue server failed. |
ERROR_DISALLOWED_BY_POLICY |
Indicates that the command failed as it violated a playback policy. |
ERROR_PLAYBACK_FAILED |
Indicates that playback of the current track has failed. |
ERROR_PLAYBACK_NO_CONTENT |
Indicates that there is no playback source. This could indicate that the queue is empty or that there is no next or previous track to play. |
ERROR_SKIP_LIMIT_REACHED |
Indicates that the user may not skip forward due to a playback policy that allows a limited number of skips per time interval. See playback policies for details. |
Examples
Examples of error states.
ERROR_CLOUD_QUEUE_SERVER
A group would send the ERROR_CLOUD_QUEUE_SERVER playbackError event after attempting to access a URL that was not found on a cloud queue:
|
1 2 3 4 5 6 7 |
{ "errorCode": "ERROR_CLOUD_QUEUE_SERVER", "reason": "Item not found", "itemId": "abc", "queueVersion": "asdf3cbjal235jazz", "httpStatus": 404 } |
ERROR_DISALLOWED_BY_POLICY
A group would send the ERROR_DISALLOWED_BY_POLICY playbackError if you set a playback policy prohibiting the command. For example, if you have the canSkipBack playback policy set to false on the container and the track and your app sent a skipToPreviousTrack command, the player would send the following response to your app:
|
1 2 3 |
{ "errorCode": "ERROR_DISALLOWED_BY_POLICY" } |
ERROR_PLAYBACK_FAILED
A group would send the ERROR_PLAYBACK_FAILED playbackError event after a failure to play:
|
1 2 3 4 5 6 7 |
{ "errorCode": "ERROR_PLAYBACK_FAILED", "reason": "Concurrent streaming limit", "itemId": "abc", "queueVersion": "asdf3cbjal235jazz", "httpStatus": 403 } |
ERROR_PLAYBACK_NO_CONTENT
A group would send the ERROR_PLAYBACK_NO_CONTENT playbackError event when you send a play command when the queue is empty, or if your app calls loadCloudQueue with an empty queue and a playOnCompletion value of true:
|
1 2 3 4 5 6 |
{ "errorCode": "ERROR_PLAYBACK_NO_CONTENT", "reason": "No content loaded", "itemId": "abc", "queueVersion": "asdf3cbjal235jazz" } |