Error handling

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 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.