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.

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.

Header

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

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.

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."

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."

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."

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.

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."

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.

---

---

Last updated: Nov 27, 2023