Alexa Music and Radio Skill API Error Response

When a music or radio skill cannot successfully handle a request, the skill must send an error response. This error response informs which response Alexa returns for the customer. 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 does not 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 is not 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 is not found in the music skill service's system.
INVALID_DIRECTIVE The request is not 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 is not shared with the user. no string

Media-specific error payload types

Value Description
INSUFFICIENT_USER_SUBSCRIPTION The user does not 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 cannot be returned.
ITEM_NOT_FOUND The skill cannot find the requested item.
CRITERIA_NOT_FOUND The selection criteria in the request cannot be found.
CONTENT_NOT_FOUND The skill cannot 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.
DEVICE_LIMIT_REACHED The user has reached the limit of the number of devices on which they can simultaneously stream.

Example

The following example demonstrates an error response for the case when a music or radio skill cannot 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."
  }
}

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. 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 is not 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 is not shared with the user. no string

Audio-specific error payload types

Value Description
CONTENT_FILTERED The user has the Explicit Language Filter 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.
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"
  }
}
Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment