Amazon Music Web API
Errors
- Overview
- Error Object
- Error Codes
- HTTP Status 400
- HTTP Status 401
- HTTP Status 403
- HTTP Status 404
- HTTP Status 422
- HTTP Status 429
- HTTP Status 500
Overview
When an error occurs, the Amazon Music Web API endpoints will return one of the standard HTTP status codes as well as an error object providing further information. Depending on the error code, specific actions may need to be taken. For example, the user may need to be shown an error message, or the client may need to redirect to a specified URL.
An example of a common error is the 401 INVALID_ACCESS_TOKEN
. The client is likely to encounter this because the ACCESS_TOKEN
used for authentication expires after one hour. When this error is encountered, the client needs to take action to refresh the access token. It can then continue as normal.
Error Object
When an error occurs, an endpoint will return data containing an error object with the following fields:
Field Name | Description | Required |
---|---|---|
status | HTTP error code | True |
code | Unique internal error code, like: RESOURCE_NOT_FOUND, ACCESS_DENIED, DEPENDENCY, etc. | True |
message | Localized error message | True |
url | URL for QR code generation on client side. | False |
reference | An ID for debugging | False |
payload | Additional error details for debugging. | False |
Example
{
"error": {
"status": "403",
"code": "AUTH_NO_MUSIC_ACCOUNT_FOUND",
"message": "No Amazon Music account found. Your Amazon account is missing required information.
Please go to the Amazon Music website on a computer web browser and update your
information. It may take several minutes for your account information to update.",
"url": "https://music.amazon.com",
"reference": "ebd91b-d17f-4b4b-bab6-4d958d2c459f",
"payload": {
"internalCode": "INTERNAL_ERROR_CODE"
}
}
}
Error Codes
The table below contains the standard error codes.
HTTP Status | Error Code | Description |
---|---|---|
400 | BAD_REQUEST | Malformed request. Check for missing query parameter. |
401 | INVALID_AUTH_TYPE | Header does not contain bearer token. |
401 | INVALID_AUTH_TOKEN | Bearer token empty. |
401 | INVALID_ACCESS_TOKEN | Access token is invalid or has expired. If the access token cannot be refreshed, the client should redirect the customer to the sign-in flow |
401 | INVALID_CLIENT_ID | Unable to identify client. Check the x-api-key header. |
401 | NO_X_API_KEY | Header x-api-key not found. |
403 | NO_MUSIC_ACCOUNT_FOUND | The user is not logged in. |
403 | DENIED_SUBSCRIPTION_TIER | The requested action cannot be accomplished at the user's current subscription tier. |
404 | RESOURCE_NOT_FOUND | The requested resource was not found. |
422 | MAX_CONCURRENCY_REACHED | The maximum number of concurrent streams has been reached. |
422 | TAKE_OVER_DEVICE_STREAMING_ERROR | Failed to take over concurrently streaming device. |
429 | THROTTLED | Too Many Requests. Rate limiting has been applied. |
500 | INTERNAL | Internal Server Error. Wait and then retry. |
These error codes are explained in more detail below.
HTTP Status 400
HTTP status 400 errors indicate a malformed request to the API.
400 BAD_REQUEST
Customer facing: No
Retry: No
Example message: Missing track IDs
This error indicates a malformed request to the API. The most common issue is that some required parameter is missing. For example, a call to /playlists/{id}/tracks
without the required trackIds
parameter in the body of the request.
HTTP Status 401
HTTP status 401 errors indicate authentication errors.
401 INVALID_AUTH_TYPE
Customer facing: No
Retry: No
Example message: Invalid authorization type provided
This error indicates that the request header does not include a bearer token.
401 NO_ACCESS_TOKEN
Customer facing: No
Retry: No
Example message: Access token not found.
This error indicates a blank or empty access token.
401 INVALID_ACCESS_TOKEN
Customer facing: No
Retry: No
Example message: Unable to resolve access for customer. Check ACCESS_TOKEN or device details.
This error indicates one of two possibilities. In the first case, the ACCESS_TOKEN
is malformed or invalid. In the second case, it has expired. Tokens used for authentication expire after one hour. If a token has expired, the client needs to take action to refresh the access token. It can then continue as normal.
401 INVALID_CLIENT_ID
Customer facing: No
Retry: No
Example message: Unable to identify client. Check the x-api-key header.
This error indicates that the x-api-key
header is invalid or malformed.
401 NO_X_API_KEY
Customer facing: No
Retry: No
Example message: Header x-api-key not found.
This error indicates that the x-api-key
in the header is not found.
HTTP Status 403
403 error codes contain customer-facing messages (and, optionally, a URL) which should be displayed to the user. The message will be provided by the API response. When a URL is provided in the error object payload, the client may use a QR code generator to display a QR code based on the URL next to the message.
403 NO_MUSIC_ACCOUNT_FOUND
Customer facing: Yes
Retry: No
Example message: Your Amazon account is missing required information. Please go to https://music.amazon.com on a computer web browser and update your information. It may take several minutes for your account information to update.
URL to display to customer: https://music.amazon.com
This error indicates that the customer is attempting to use the Amazon Music service either while not logged in or without having created an account.
403 DENIED_SUBSCRIPTION_TIER
Customer facing: Yes
Retry: No
Example message: Your current subscription tier FREE is not supported on this platform. Please consider upgrading to: PRIME, UNLIMITED.
URL to display to customer: https://music.amazon.com
This error indicates that the customer is attempting to use a feature of the Amazon Music service from a tier that they are not currently subscribed to.
HTTP Status 404
404 error codes indicate that the requested API resource was not found.
404 RESOURCE_NOT_FOUND
Customer facing: No
Retry: No
Example message: The requested resource was not found.
Error indicates the requested resource was not found. Be sure to check the URI to make sure any query parameters such as id
are correct.
HTTP Status 422
422 error codes indicate playback errors.
422 MAX_CONCURRENCY_REACHED
Customer facing: Yes
Retry: No
Example message: The maximum number of concurrent streams has been reached.
Error indicates that the customer has exceeded the number of streams allowed by their current subscription. In most cases, the customer should be shown an error message indicating the problem. If the customer’s device cannot display error messages, or if interrupting the customer would be dangerous (such as in a car audio system) the client can instead attempt to take over one of the other streaming devices to halt playback.
422 TAKE_OVER_DEVICE_STREAMING_ERROR
Customer facing: Yes
Retry: No
Example message: Failed to take over device streaming.
Error indicates that an attempt to take over a device, most commonly when that device is causing a customer to exceed the maximum number of concurrently streaming devices, has failed. The customer should be shown an error message indicating that they are over the number of concurrently streaming devices allowed for their account, and informed that they will need to stop playback on another device to continue playback on this one.
HTTP Status 429
429 error codes indicate throttling.
429 THROTTLED
Customer facing: No
Retry: No
Example message: Too Many Requests. Rate limiting has been applied.
This error indicates that the client has made too many requests to the API and that the rate limit has been applied. When seeing this error, determine whether there is a bug causing your client to make an excessive number of requests. If the requests are determined to be legitimate, get in touch with your Amazon Music contact person to request a limit increase.
HTTP Status 500
500 error codes indicate internal errors.
500 INTERNAL
Customer facing: No
Retry: Yes
Example message: Internal Server Error.
This error indicates an internal server error has occurred within the Amazon Music service. Most such errors will be resolved quickly and automatically. The best strategy for this type of error is to wait and retry. You may choose to implement something like an exponential backoff algorithm to determine how long to wait before the next retry.