Amazon Music Web API

Errors

Important: These Amazon Music documents are in preview status. Be aware that content may change. Please use the developer forum for any questions or comments.

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.