Amazon Music Device API

Warning: This API is DEPRECATED. Please avoid using this API and consider migrating to the new Web API.

Errors

In addition to resource-specific errors, any request may fail with a general error that may require some user action to resolve the error condition. General errors may be raised under a variety of circumstances—for example, customer subscription and billing issues, concurrent streaming violations, and Amazon service interruptions. A general error is indicated by a response status code of 409 Conflict. The response entity will be a GeneralErrorReport document. If there is a problem with a particular track, the TrackDefinition’s error member will be a local reference to a general error report.

Upon receiving a general error response, a client must:

Present to the user the error message contained in the general error report.
Perform the actions associated with the user’s choice.
If the error occurs during playback, then pause any active audio streams (unless the error is on a trackDefinition that has autoSkipOnError = true)

GeneralErrorReport fields

The following fields can be found in a GeneralErrorReport document:

Field name	Type	Description
terse	string	A short message describing the error, intended for space-constrained presentations where the explanation and brief messages cannot be shown together.
brief	string	A short message describing the error, intended to be presented together with the explanation message.
explanation	string	A detailed message describing the error, encoded as an HTML fragment where only the A[href] and BR elements will be used.
options	array of objects	An array of objects, each describing an option that the user may choose. The array may be empty. See below table for list of valid options.

GeneralErrorReport options

The options field of a GeneralErrorReport document can contain the following possible values:

Option name	Value	Description
label	string	A label that describes this option
resume	boolean	If true, then any streams that were paused as a result of the general error should be resumed when the user chooses this option. If false, streams should remain paused until the user resumes them manually.
action	string	* If the action is "post," the client should send a POST request when the user chooses this option. After receiving a response, any locally cached data must be invalidated. * If the action is "www," the client should open the system Web browser when the user chooses this option. When the user returns to the client application, any locally cached data must be invalidated. * If the action is null or empty, the client should take no action other than dismissing the error message and resuming playback (if resume = true).
uri	string	The URI to which the POST request should be sent when the action is "post," or to which the URI should be loaded in the system web browser when the action is "www." If the URI is null or empty, no URI is associated with this option's action.

Handling Errors

Client applications can choose between two presentation forms when presenting error messages to the user. In the full form, the application displays both the brief and the explanation messages provided in the General Error Report object, in that order. In many cases, the brief string will be the title of a message screen or dialog, and the explanation will be the body. In the terse form, the application displays only the message provided in the terse member; this form is intended only for space-constrained presentations. The full form should be used whenever possible.

If a general error response is received when performing audio playback while there is no active user-interface component capable of presenting the error message (for example, if the client is controlled by a mobile device that is powered off at the moment), the client must pause audio streams immediately (except in the case where autoSkipOnError = true), and defer presenting the error message until such user-interface component becomes active again.

Retry Strategies for Errors

There exists the possibility of errors in cases where there are network issues, service outages or you have exceeded your throughput limits. Exceeding the throughput limit will result in a 429 response code. When a client makes a request and encounters this type of error, the best strategy is to wait and retry. An approach known as “exponential back off” can help avoid overloading the service further while still checking at slowly increasing intervals for a connection. The following pseudocode shows one way to handle this:

Do some asynchronous operation.

retries = 0

DO
    wait for (2^retries * 100) milliseconds

    status = Get the result of the asynchronous operation.

    IF status = SUCCESS
        retry = false
    ELSE IF status = NOT_READY
        retry = true
    ELSE IF status = THROTTLED
        retry = true
    ELSE
        Some other error occurred, so stop calling the API.
        retry = false
    END IF

    retries = retries + 1

WHILE (retry AND (retries < MAX_RETRIES))

Please note: ordinary 409 errors return a GeneralErrorReport which should be handled as described in the sections above. Exponential back off should not be used for these kinds of errors.