Alexa Music, Radio, and Podcast Skill API Error Response

When a music, radio, or podcast skill can't successfully handle a request, the skill must send an error response. This page explains the types of error responses a skill can send.

General errors

In some cases, the music or radio skill should return a generic Alexa.ErrorResponse message with the appropriate error type. For more information, see the error types and their descriptions in the following table.

Error type Description
ACCOUNT_PROBLEM The user's account with the music service provider has a problem that prevents the user from using the skill. The user should work with the music service provider to resolve the problem. For example, you might use this error when the user's account has not been used for a long time and needs to be reactivated. After resolving the problem with the music service provider, the user should not need to re-link their account.
EXPIRED_AUTHORIZATION_CREDENTIAL The authorization credential in the request is expired.
INTERNAL_ERROR Use this type for any error doesn't fit into one of the other error types. For example, use this when a generic runtime exception occurred while handling a request. Ideally, a skill should never send this error type, but instead send a more specific error type. When this error type is returned to Alexa for any interface, the playback session stops and all state is thrown away.
INVALID_AUTHORIZATION_CREDENTIAL The authorization credential in the request is invalid. For example, the OAuth 2.0 access token isn't valid for the user's account with the music skill service. You can also use this error type when the access token in the request isn't found in the music skill service's system.
INVALID_DIRECTIVE The request isn't valid for this skill or is malformed. Use this error type when your skill receives a request for an interface that it doesn't support.
RATE_LIMIT_EXCEEDED The user has exceeded their rate limit when using the skill.

Example

The following example demonstrates an error response for the case when a music skill receives a request with an expired OAuth 2.0 access token.

{
  "header": {
    "messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
    "namespace": "Alexa",
    "name": "ErrorResponse",
    "payloadVersion": "3.0"
  },
  "payload": {
    "type": "EXPIRED_AUTHORIZATION_CREDENTIAL",
    "message": "The authorization credential provided by Alexa has expired."
  }
}

ACCOUNT_PROBLEM error subtypes

Error subtype Description
INACTIVE_SUBSCRIPTION The user's account has been closed, their subscription is no longer valid, or the user's account has not been used for a long time and needs to be reactivated. In all cases, the only resolution is for the user to contact their music service provider.
NOT_SUBSCRIBED The user's subscription does not allow access to this content. The user needs to contact their music service provider to change their subscription.
PAYMENT_PROBLEM A problem occurred with the payment method that the user used when subscribing to the service. For example, the user supplied an expired credit card, or they exceeded their credit limit.

Media-specific errors

In some cases, the music skill should return a media-specific error response. For more information, see the following tables and example.

For an overview of the header format, see message header.

Field Value Required? Type
messageId A version 4 UUID yes string
namespace Alexa.Media yes string
name ErrorResponse yes string
payloadVersion 1.0 yes string

Payload

The following table describes the fields in the payload of a media-specific error response.

Field Description Required? Type
type Indicates the kind of error that occurred. Alexa uses this field to respond to the user appropriately. See the following table for the allowed values. yes string
message Information about the error for logging purposes. This information isn't shared with the user. no string

Media-specific error payload types

Value Description
CONTENT_FILTERED The user has the Explicit Language Filter (ELF) turned on, but the skill can't find any non-explicit content for the user's request. GetPlayableContent and Initiate can return this error code.
INSUFFICIENT_USER_SUBSCRIPTION The user doesn't have a subscription level that allows the requested content.
INVALID_ITEM The skill can find the requested item, but the item is invalid for the request and can't be returned.
ITEM_NOT_FOUND The skill can't find the requested item.
CRITERIA_NOT_FOUND The selection criteria in the request can't be found.
CONTENT_NOT_FOUND The skill can't find the requested content.
GEOGRAPHICAL_RESTRICTION_ERROR The user's location, as passed in the request, prevents the skill from satisfying the request due to geographical restrictions. See Implement availability checking.
DEVICE_LIMIT_REACHED The user has reached the limit of the number of devices on which they can simultaneously stream.

CONTENT_FILTERED error subtypes

Error subtype Description
EXPLICIT_LANGUAGE_FILTER To ensure customers get the correct ELF prompt when the Explicit Language Filter is triggered, add EXPLICIT_LANGUAGE_FILTER as a subtype in the error response payload.

CONTENT_NOT_FOUND error subtypes

Error subtype Description
NO_FOLLOWED_CONTENT The customer hasn't subscribed to or followed any podcast.

Examples

The following example demonstrates an error response for the case when the Explicit Language Filter is triggered.

CONTENT_FILTERED error

{
  "header": {
    "messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
    "namespace": "Alexa.Media",
    "name": "ErrorResponse",
    "payloadVersion": "1.0"
  },
    "payload": {
        "type": "CONTENT_FILTERED",
        "message": "",
        "subtypes": [
            "EXPLICIT_LANGUAGE_FILTER"
        ]
   }
}

CONTENT_NOT_FOUND error

The following example demonstrates an error response for the case when a music or radio skill can't find the requested content.

{
  "header": {
    "messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
    "namespace": "Alexa.Media",
    "name": "ErrorResponse",
    "payloadVersion": "1.0"
  },
  "payload": {
    "type": "CONTENT_NOT_FOUND",
    "message": "The requested content could not be found."
  }
}

The following examples demonstrate responses for podcast subscription play errors.

Podcast content search errors

In the following example, the customer hasn't subscribed to or followed any podcast. Alexa renders the error prompt, "To play the latest episodes from the podcasts in your library, you'll first need to Follow podcasts in your <provider> app."

{
  "header": {
    "messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
    "namespace": "Alexa.Media",
    "name": "ErrorResponse",
    "payloadVersion": "1.0"
  },
  "payload": {
    "type": "CONTENT_NOT_FOUND",
    "subtypes": [
      "NO_FOLLOWED_CONTENT"
    ],
    "message": "No content available as the user has not followed or subscribed to any content source."
  }
}

In the following example, there are no new episodes to play. In this case, the provider returns a GetPlayableContent response to indicate that the customer does not have any episodes to listen to in the podcasts they subscribe to. Alexa renders the error prompt, "You're up to date with all the episodes from the podcasts you follow."

{
  "header": {
    "messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
    "namespace": "Alexa.Media",
    "name": "ErrorResponse",
    "payloadVersion": "1.0"
  },
  "payload": {
    "type": "CONTENT_NOT_FOUND",
    "subtypes": [
      "NO_NEW_CONTENT"
    ],
    "message": "No content available due to prior consumption."
  }
}

If the provider can't create a subscription play queue for the customer, the provider can return the following generic "content not found" error response to the GetPlayableContent request. Alexa renders the error prompt, "<Provider> didn't find any episodes in your podcast library."

{
  "header": {
    "messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
    "namespace": "Alexa.Media",
    "name": "ErrorResponse",
    "payloadVersion": "1.0"
  },
  "payload": {
    "type": "CONTENT_NOT_FOUND",
    "message": "Requested content could not be found."
  }
}

Podcast navigation errors

The following example applies to subscription and non-subscription podcast play queues. In this case, the customer has reached the end of the play queue. The provider should respond to the GetNextItem request with a payload in which the isQueueFinished flag is true.

{
  "header": {
    "messageId": "<messageId>",
    "namespace": "Alexa.Audio.PlayQueue",
    "name": "GetNextItem.Response"
  },
  "payload": {
    "isQueueFinished": true
  }
}

The following example applies to subscription and non-subscription podcast play queues. In this case, the first episode in subscription queue is playing, and the customer asks for the previous episode. The provider should respond to the GetNextItem request with an error response of type ITEM_NOT_FOUND. Alexa renders the error prompt, "You're currently listening to the first episode in this play queue."

{
  "header": {
    "messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
    "namespace": "Alexa.Media",
    "name": "ErrorResponse",
    "payloadVersion": "1.0"
  },
  "payload": {
    "type": "ITEM_NOT_FOUND",
    "message": "There is no previous item."
  }
}

Audio-specific errors

In some cases, the music skill should return an audio-specific error response. For more information, see the following tables and example.

Header

For an overview of the header format, see message header.

Field Value Required? Type
messageId A version 4 UUID yes string
namespace Alexa.Audio yes string
name ErrorResponse yes string
payloadVersion 1.0 yes string

Payload

The following table describes the fields in the payload of an audio-specific error response.

Field Description Required? Type
type Indicates the kind of error that occurred. Alexa uses this field to respond to the user appropriately. The only allowed value is SKIP_LIMIT_REACHED, which indicates that the user has reached their skip limit. With this error type, the skill can return an optional parameter which Alexa can use to render an error prompt (VUI) or display an error message (GUI) informing the user how long they should wait before trying to skip again. yes string
retryPeriod Indicates how long the user needs to wait before attempting to skip again. Alexa uses this value to render a helpful voice prompt or a visual message. Supported values are HOURLY, DAILY, and UNKNOWN.

Returning HOURLY causes Alexa to prompt the user to retry their skip command the next day. Returning DAILY causes Alexa to prompt the user to retry their skip command the next hour. Returning UNKNOWN causes Alexa to prompt the user to retry their skip command "later," without specifying a time period. UNKNOWN is the default value when this field isn't specified in the error response.

For example, imagine that a user reached their daily skip limit and asks Alexa to skip to the next song. Returning DAILY for this field causes Alexa to say, "You don't have any skips left for the day. Please try again tomorrow."		 no string
message Information about the error for logging purposes. This information isn't shared with the user. no string

Audio-specific error payload types

Value Description
SKIP_LIMIT_REACHED The user has reached their skip limit. The skill can return an optional retryPeriod value, which Alexa uses to tell the user how long to wait before they try to skip again.

Example

The following example demonstrates an error response for the case when a music skill determines that the user has reached their daily skip limit.

{
  "header": {
    "messageId": "2cae4d53-6bc1-4f8f-aa98-7dd2727ca84b",
    "namespace": "Alexa.Audio",
    "name": "ErrorResponse",
    "payloadVersion": "1.0"
  },
  "payload": {
    "type": "SKIP_LIMIT_REACHED",
    "message": "The user has reached their daily skip limit.",
    "retryPeriod": "DAILY"
  }
}
Was this page helpful?

Last updated: Nov 27, 2023