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 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.
Note: The
payloadVersion field for error messages in the Alexa namespace is always 3.0.| 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. |
Note: When your skill code (AWS Lambda function) returns an HTTP 500 error when invoking a skill, Alexa stops the playback session and throws away all state related to that session. However, Alexa also attempts to retry with exponential back-off.
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."
}
}
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.
Note: The
payloadVersion field for error messages in the Alexa.Media namespace is always 1.0.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 is not shared with the user. | no | string |
Error payload type values
| 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.
Note: The
payloadVersion field for error messages in the Alexa.Audio namespace is always 1.0.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 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 |
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"
}
}
