Amazon Music Device API
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
autoSkipOnError = true)
The following fields can be found in a
|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.|
options field of a
GeneralErrorReport document can contain the following possible values:
|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.|
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.