Sign In
Sign In

Amazon Music Web API

Errors

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.