Web API Errors V2.0

Important: These Amazon Music APIs are currently in a closed Beta. Please check back soon for updates.

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.

Web API V2 Errors

Amazon Music Web API V2 returns errors in a consistent shape. Every error response carries a single top-level error object:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource could not be found.",
    "traceId": "1-abc-def"
  }
}

code — a stable, machine-readable error code (see below).
message — a human-readable description of what went wrong.
traceId — an identifier that correlates this request with Amazon Music's service-side logs. Include the traceId when you contact your Amazon Music point-of-contact about a failed request; it lets support locate the exact transaction.

Error codes

The V2 reference uses the following error codes. The HTTP status is returned on the response, and the same code appears in the error.code field.

Code	HTTP status	Example message
`BAD_REQUEST`	400	`first parameter must be between 1 and 100`
`UNAUTHORIZED`	401	`Authentication required`
`FORBIDDEN`	403	`Loop is not available for this queue`
`NOT_FOUND`	404	`Album not found`
`NO_MORE_NEXT_ENTITY`	404	`No more entities in the queue`
`NO_MORE_PREVIOUS_ENTITY`	404	`No more previous entities in the queue`
`MAX_CONCURRENCY_REACHED`	429	`Concurrent stream limit exceeded`
`INTERNAL`	500	`An unexpected error occurred`

The NO_MORE_NEXT_ENTITY, NO_MORE_PREVIOUS_ENTITY, and MAX_CONCURRENCY_REACHED codes are specific to the Playback APIs — the first two signal that queue navigation has reached an end of the queue, and MAX_CONCURRENCY_REACHED signals that the account's concurrent stream limit has been reached. See Playback API Concepts for how playback surfaces these.

The reference is authoritative

Not every endpoint can return every code. The Error Responses table on each reference page lists exactly which codes and messages that endpoint returns, and is the authoritative source for error handling. Consult the specific reference page for the endpoint you are calling.