ErrorResponse
Alexa.ErrorResponseインターフェース
Alexaからスキルに送られたリクエストを正常に処理できない場合は、Alexa.ErrorResponse
イベントを返します。エラータイプとその理由を指定してください。応答は同期または非同期のどちらでも可能です。非同期で応答する場合、相関トークンと、認可トークンを含めたスコープを含めます。
エラー応答イベント
Alexa.ErrorResponse
のペイロードでは、エラータイプを指定し、エラー情報のメッセージを含めます。エラータイプの一覧については、エラータイプの値を参照してください。
ErrorResponseイベントのペイロードの詳細
フィールド | 説明 | タイプ | 必須 |
---|---|---|---|
type |
エラーのタイプです。Alexaはこれをユーザーと共有します。 | 文字列 | ◯ |
message |
エラーのエラーメッセージです。この情報はユーザーとは共有されません。 | 文字列 | ◯ |
注: エラーのタイプによっては、ペイロードの内容が追加される場合があります。詳細については、エラータイプの値を参照してください。
ErrorResponseイベントの形式
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ErrorResponse",
"messageId": "<メッセージID>",
"payloadVersion": "3"
},
"endpoint":{
"endpointId": "<エンドポイントID>"
},
"payload": {
"type": "<エラータイプ>",
"message": "<エラーメッセージ>"
}
}
}
エラータイプの値
以下の表に有効なエラータイプを示します。
注:
ErrorResponse
の型が異なる場合、必ずしもAlexaが異なる応答を発話するとは限りません。フィールド | 説明 |
---|---|
ALREADY_IN_OPERATION | エンドポイントが既に稼動中であるため、処理を実行できません。 |
BRIDGE_UNREACHABLE | ブリッジが到達できない状態であるか、オフラインになっています。たとえば、ブリッジがオフになっている、ユーザーのローカルエリアネットワークから切断されている、ブリッジとデバイス制御クラウドの間の接続が切断されているなどです。ReportState ディレクティブに応答するときに、このエラーではなくStateReport を返す必要が生じるケースがあります。詳細については、Alexa.EndpointHealthを参照してください。 |
ENDPOINT_BUSY | ターゲットとするエンドポイントが別のアクションを実行しているため、ディレクティブを処理できません。このアクションは、Alexaへのリクエストに基づいて実行されている場合と、そうでない場合があります。 |
ENDPOINT_LOW_POWER | エンドポイントのバッテリー残量が足りないため、ディレクティブを処理できません。 |
ENDPOINT_UNREACHABLE | エンドポイントが到達できない状態であるか、オフラインになっています。たとえば、エンドポイントがオフになっている、ユーザーのローカルエリアネットワークから切断されている、エンドポイントとブリッジまたはエンドポイントとデバイス制御クラウドの間の接続が切断されているなどです。ReportState ディレクティブに応答するときに、このエラーではなくStateReport を返す必要が生じるケースがあります。詳細については、Alexa.EndpointHealthを参照してください。 |
EXPIRED_AUTHORIZATION_CREDENTIAL | Alexaが提供する認可資格情報が期限切れです。ユーザーのOAuth2アクセストークンが期限切れになっている場合などです。 |
FIRMWARE_OUT_OF_DATE | エンドポイントのファームウェアが期限切れになっているため、ディレクティブを処理できません。 |
HARDWARE_MALFUNCTION | エンドポイントでハードウェアの故障が発生したため、ディレクティブを処理できません。 |
INSUFFICIENT_PERMISSIONS | Alexaには、指定されたアクションをエンドポイントで実行する権限がありません。 |
INTERNAL_ERROR | 特定のエラータイプでは説明できないエラーが発生しました。ランタイム例外が発生した場合などがこれにあたりますが、常に具体的なエラータイプを送信することをお勧めします。 |
INVALID_AUTHORIZATION_CREDENTIAL | Alexaが提供する認可資格情報が無効です。ユーザーのデバイス制御クラウドアカウントでOAuth2アクセストークンが有効でない場合などです。 |
INVALID_DIRECTIVE | ディレクティブがこのスキルでサポートされていないか、正しくありません。 |
INVALID_VALUE | ディレクティブに、ターゲットとするエンドポイントでは無効の値が含まれています。たとえば、暖房モード、チャンネル値、プログラム値などが無効の場合です。 |
NO_SUCH_ENDPOINT | ターゲットとするエンドポイントが存在しない、または存在しなくなりました。 |
NOT_CALIBRATED | エンドポイントが較正中(暖機中など)のため、ディレクティブを処理できません。 |
NOT_SUPPORTED_IN_CURRENT_MODE | 現在の操作モードが原因で、エンドポイントを指定された値に設定できません。このエラー応答を送信する場合は、デバイスを新しい値に設定できない理由を示すcurrentDeviceMode フィールドをペイロードに含めてください。たとえば、白色照明ではない電球の色温度設定は調整できません。詳細については、Alexa.ColorTemperatureControlを参照してください。 |
NOT_IN_OPERATION | エンドポイントが稼働していません。たとえば、スマートホームスキルがRESUME ディレクティブを受け取ったが、エンドポイントがOFF モードの場合、NOT_IN_OPERATIONエラーを返すことができます。 |
POWER_LEVEL_NOT_SUPPORTED | エンドポイントがサポートしていない電力レベルの操作がリクエストされたので、ディレクティブを処理できません。 |
RATE_LIMIT_EXCEEDED | エンドポイントまたはブリッジがディレクティブを処理できる最大レートを超えています。 |
TEMPERATURE_VALUE_OUT_OF_RANGE | 許容される温度の範囲外であるため、エンドポイントを指定された値に設定できません。このエラー応答を送信する場合は、オプションとして、有効な温度範囲を示すvalidRange フィールドをペイロードに含めることができます。詳細については、例を参照してください。サーモスタット固有のその他のエラーについては、Alexa.ThermostatControllerインターフェースを参照してください。 |
VALUE_OUT_OF_RANGE | 許容される数値の範囲外であるため、エンドポイントを指定された値に設定できません。たとえば、ユーザーが100を超えるパーセンテージ値をリクエストした場合にこのエラーを使用できます。温度値には、代わりにTEMPERATURE_VALUE_OUT_OF_RANGE を使用します。このエラー応答を送信する場合は、オプションとして、有効な数値範囲を示すvalidRange フィールドをペイロードに含めることができます。詳細については、例を参照してください。 |
例
同期エラー応答の例
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ErrorResponse",
"messageId": "<メッセージID>",
"payloadVersion": "3"
},
"endpoint":{
"endpointId": "<エンドポイントID>"
},
"payload": {
"type": "ENDPOINT_UNREACHABLE",
"message": "エンドポイント12345にアクセスできません。オフラインの可能性があります"
}
}
}
非同期エラー応答の例
非同期で応答する場合、相関トークンと、認可トークンを含めたスコープを含めます。
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ErrorResponse",
"messageId": "<メッセージID>",
"correlationToken": "<opaque相関トークン>",
"payloadVersion": "3"
},
"endpoint":{
"scope":{
"type":"BearerToken",
"token":"access-token-from-Amazon"
},
"endpointId": "<エンドポイントID>"
},
"payload": {
"type": "ENDPOINT_UNREACHABLE",
"message": "エンドポイント12345にアクセスできません。オフラインの可能性があります"
}
}
}
VALUE_OUT_OF_RANGEエラー応答の例
VALUE_OUT_OF_RANGE
エラータイプとともにvalidRange
オブジェクトを使用して、設定できる最小値と最大値を指定します。
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ErrorResponse",
"messageId": "<メッセージID>",
"payloadVersion": "3"
},
"endpoint":{
"endpointId": "<エンドポイントID>"
},
"payload": {
"type": "VALUE_OUT_OF_RANGE",
"message": "100を超えるパーセンテージ値は設定できません。",
"validRange": {
"minimumValue": 0,
"maximumValue": 100
}
}
}
}
TEMPERATURE_VALUE_OUT_OF_RANGEエラー応答の例
TEMPERATURE_VALUE_OUT_OF_RANGE
エラータイプとともにvalidRange
オブジェクトを使用して、有効な最高温度と最低温度を指定します。最大値と最小値は、温度オブジェクトを含みます。
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ErrorResponse",
"messageId": "<メッセージID>",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "<エンドポイントID>"
},
"payload": {
"type": "TEMPERATURE_VALUE_OUT_OF_RANGE",
"message": "リクエストされた温度-15は範囲外です。",
"validRange": {
"minimumValue": {
"value": 15.0,
"scale": "CELSIUS"
},
"maximumValue": {
"value": 30.0,
"scale": "CELSIUS"
}
}
}
}
}
ENDPOINT_LOW_POWERエラー応答の例
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ErrorResponse",
"messageId": "<メッセージID>",
"payloadVersion": "3"
},
"endpoint": {
"endpointId": "<エンドポイントID>"
},
"payload": {
"type": "ENDPOINT_LOW_POWER",
"message": "ロックのバッテリー残量が足りません",
"percentageState": 5
}
}
}