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 OperationControl API CommandCloud Queue RequestsError Response
Load and start playing a track in a playlistloadCloudQueue/itemWindowUser 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 playlistskipToItem/version or /itemWindowUser 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 queuerefreshCloudQueue/itemWindowUser 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 OperationDescriptionError Response
Next WindowPlayers 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 PollPlayers 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.
RetryThe 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 ErrorsDescriptionRetry LimitRetry wait time
Incomplete requestsThese include connection failures and any error where a complete response is not received from the server.32 seconds.
Service UnavailableThis is a 503 HTTP error code by the server with a Retry-After HTTP header.3As specified in header. Limited to a range of 2-10 seconds.
Other Server ErrorsThese include any other server error response code and any success response code where the message is malformed in some way.No RetriesN/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 CodeNameDescription
400Bad RequestGeneral errors with the player's request. For example, the previousWindowSize or upcomingWindowSize for /itemWindow were negative (they should be zero or greater).
401UnauthorizedThe access token has expired or is invalid.
403ForbiddenReason can be returned in the X-Rejected-Reason HTTP header for your cloud queue server, for logging purposes.
404Not FoundPlayer evicts the session, except for GET /itemWindow. For GET /itemWindow, the player empties the queue and waits for more content.
500Internal Server ErrorInternal Server error. The player should not retry (see above).
503Service UnavailableThe player will retry after the time in the Retry-After HTTP header.