Error handling (Cloud Queue)

This page describes the different types of cloud queue errors that players expect and how players respond to the errors. Your cloud queue server should be able to handle the player behavior described below, particularly the background operations and the retries.

Cloud Queue HTTP error response body

Here's an example of an error response body that a player expects from a cloud queue server:

{
  "error": {
   "errors": [
    {
     "domain": "global",
     "reason": "backendError",
     "message": "Backend Error"
    }
   ],
   "code": 500,
   "message": "Backend Error"
  }
}

Error responses for user-initiated operations

User-initiated operations are operations requested by a user on your app, which your app sends as a Sonos Control API command to a player. An example of this is when a player presses the next track button to skip to the next track. In general, the player will not retry cloud queue operations on failures before sending the response, since the user is waiting on the operation. However, some failures may be retried as part of the background processing that occurs on players for robustness.

User Operation	Control API Command	Cloud Queue Requests	Error Response
Load and start playing a track in a playlist	`loadCloudQueue`	`/itemWindow`	User operation will fail, an error response will be returned, and the request will not be retried. The player will remain in the previous playback state (paused at end or idle).
Skip to a track in the playlist	`skipToItem`	`/version` or `/itemWindow`	User operation will continue with the current window and track data (a success response will be returned), but the request will be retried in the background.
Modified the queue	`refreshCloudQueue`	`/itemWindow`	User operation will continue (a success response will be returned), but the request will be retried in the background.

Error responses for player background operations

These are cloud queue operations that occur on the player automatically and are based on time or progression through the current window of tracks.

Background Operation	Description	Error Response
Next Window	Players send an `/itemWindow` request when playback reaches the edges of the current window of tracks, typically around 2-3 tracks before the edge of the window.	Request will be retried in the background.
Queue Version Poll	Players send a `/version` request while playing or paused, which then causes an `/itemWindow` request if the queue version has changed. When paused, players poll the cloud queue every 5 minutes, and when playing every 10 minutes.	Request will be retried in the background.
Retry	The last failed user-initiated or background request will be repeated after a wait time.	Request will be retried.

Players retry background cloud queue requests up to three times. This results in four total request tries, including the original request. Players wait 10 seconds after the original request to retry and then another 10 seconds before retrying again.

If the player uses all the retries without a successful response, it will play what it has left in the current itemWindow and then enter a pause state. The player keeps the playback session valid when this happens.

Players retry requests depending on the error

Players retry requests depending on the type of error returned by your cloud queue server. If the the player reaches the retry limit, an error will be reported to the app and the player will stop playback of the cloud queue and go to an idle playback state.

Types of Errors	Description	Retry Limit	Retry wait time
Incomplete requests	These include connection failures and any error where a complete response is not received from the server.	3	2 seconds.
Service Unavailable	This is a `503` HTTP error code by the server with a `Retry-After` HTTP header.	3	As specified in header. Limited to a range of 2-10 seconds.
Other Server Errors	These include any other server error response code and any success response code where the message is malformed in some way.	No Retries	N/A

HTTP error codes

These HTTP error codes should be returned by your cloud queue server when there are errors. 4xx errors are player (client) errors. 5xx errors are cloud queue (server) errors.

Error Code	Name	Description
`400`	Bad Request	General errors with the player's request. For example, the `previousWindowSize` or `upcomingWindowSize` for `/itemWindow` were negative (they should be zero or greater).
`401`	Unauthorized	The access token has expired or is invalid.
`403`	Forbidden	Reason can be returned in the `X-Rejected-Reason` HTTP header for your cloud queue server, for logging purposes.
`404`	Not Found	Player evicts the session, except for GET /itemWindow. For GET /itemWindow, the player empties the queue and waits for more content.
`500`	Internal Server Error	Internal Server error. The player should not retry (see above).
`503`	Service Unavailable	The player will retry after the time in the `Retry-After` HTTP header.