ErrorResponse



Alexa.ErrorResponse

制御またはクエリーのディレクティブを処理中にエラーが発生した場合、ErrorResponseイベントを返す必要があります。このイベントは、Alexa名前空間に含まれます。このメッセージには、エラーのタイプとその理由を指定するペイロードが含まれている必要があります。

エラーメッセージの形式

ErrorResponseイベントのペイロードでは、typemessageを指定する必要があります。

  • type: 発生したエラーのタイプを示す、受け取ったタイプ値の1つです。Alexaはこのアトリビュートを使用して、ユーザーに応答します。
  • message: ログを記録するために、詳細なエラー情報を提供する文字列です。この情報がユーザーと共有されることはありません。

タイプによっては、ペイロードの内容が追加される場合があります。

記述されるエラータイプは特定の機能のインターフェースだけでなく、あらゆる制御やクエリーのディレクティブの応答にも使用されます。検出リクエスト中に期限切れトークンなどのエラーが発生した場合は、エラーではなく空のエンドポイント配列が返されます。インターフェースに固有のエラーについては、インターフェース別のトピックを参照してください。

エラータイプの値

タイプ説明ペイロード/特記事項
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ブリッジまたはエンドポイントでハードウェアの故障が発生したために、ディレクティブを処理できなかったことを示します。なし
INTERNAL_ERRORディレクティブの処理中に他のエラータイプのいずれかが発生したために、正確に説明できないエラーを示します。ディレクティブの処理中に一般的なランタイム例外が発生した場合などです。このエラーイベントではなく、具体的なエラータイプを送信することをお勧めします。なし
INVALID_
AUTHORIZATION_CREDENTIAL
Alexaが提供する認可資格情報が無効であることを示します。ユーザーのデバイス制御クラウドアカウントでOAuth2アクセストークンが有効でない場合などです。なし
INVALID_DIRECTIVEディレクティブがこのスキルに対して有効ではない、または形式が正しくないことを示します。なし
INVALID_VALUEターゲットとするエンドポイントのディレクティブに無効な値が含まれていることを示します。たとえば、リクエストに含まれる暖房モードやチャンネル値、プログラム値が無効であることを示すために使用します。なし
NO_SUCH_ENDPOINT ターゲットとするエンドポイントが存在しない、または存在しなくなったことを示します。なし
NOT_SUPPORTED_
IN_CURRENT_MODE
現在の操作モードが原因でターゲットとするエンドポイントを指定された値に設定できないことを示します。デバイスを新しい値に設定できない理由をcurrentDeviceModeフィールドで示す必要があります。有効な値は、COLORASLEEPNOT_PROVISIONEDOTHERです。Alexa.ColorTemperatureControlで例を参照してください。
NOT_IN_OPERATIONエンドポイントが稼動していないため、リクエストされた処理を実行できないことを示します。たとえば、スマートホームスキルがTimeHoldController.Resumeディレクティブを受け取ったときにエンドポイントがオフモードである場合、NOT_IN_OPERATIONエラーを返します。なし
POWER_LEVEL_
NOT_SUPPORTED
エンドポイントがサポートしていない電力レベルの操作がリクエストされたことを示します。なし
RATE_LIMIT_EXCEEDED エンドポイントまたはブリッジがディレクティブを処理できる最大レートを超えていることを示します。なし
TEMPERATURE_
VALUE_OUT_OF_RANGE
ディレクティブに含まれる値が、対象のサーモスタットで許容される温度の範囲外であることを示します。サーモスタットに固有のその他のエラーについては、Alexa.ThermostatControllerインターフェースのエラーのセクションを参照してください。オプションとして、validRangeオブジェクトを使用して有効な温度の範囲を指定できます。このエラータイプの最大値と最小値は、Temperatureオブジェクトです。TEMPERATURE_
VALUE_OUT_OF_RANGE
の例を参照してください。
VALUE_OUT_OF_RANGEディレクティブに含まれる値が、ターゲットのエンドポイントで許容される数値の範囲外であることを示します。たとえば、100を超えるパーセンテージ値を設定するリクエストに応答する場合に使用します。温度値には、TEMPERATURE_VALUE_OUT_OF_RANGEを使用します。オプションとして、validRangeオブジェクトのminimumValueフィールドとmaximumValueフィールドで有効な範囲を指定できます。VALUE_OUT_RANGEの例を参照してください。

同期的なErrorResponseの例

{
"event": {
    "header": {
      "namespace": "Alexa",
      "name": "ErrorResponse",
      "messageId": "a9a87be3-a41a-43c4-b734-04a8fcaf9d3c",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "endpoint":{
        "endpointId":"appliance-001"
    },
    "payload": {
      "type": "ENDPOINT_UNREACHABLE",
      "message": "エンドポイント12345にアクセスできません。オフラインの可能性があります"
    }
  }
}

非同期的なErrorResponseの例

{
"event": {
    "header": {
      "namespace": "Alexa",
      "name": "ErrorResponse",
      "messageId": "a9a87be3-a41a-43c4-b734-04a8fcaf9d3c",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "endpoint":{
       "scope":{
          "type":"BearerToken",
          "token":"access-token-from-Amazon"
       },
       "endpointId":"appliance-001"
    },
    "payload": {
      "type": "ENDPOINT_UNREACHABLE",
      "message": "エンドポイント12345にアクセスできません。オフラインの可能性があります"
    }
  }
}

validRangeオブジェクト

有効な範囲には、その設定で有効な値となる、1つ以上のオブジェクトが含まれます。VALUE_OUT_OF_RANGEのエラータイプでは、validRangeオブジェクトのminimumValueおよびmaximumValueを使用して設定値の範囲を指定します。ThermostatControllerで使用する場合、validRangeには、minimumValuemaximumValueを指定する1つ以上のTemperatureオブジェクトが含まれます。

VALUE_OUT_RANGEエラーの例

{
"event": {
    "header": {
      "namespace": "Alexa",
      "name": "ErrorResponse",
      "messageId": "a9a87be3-a41a-43c4-b734-04a8fcaf9d3c",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "endpoint":{
       "scope":{
          "type":"BearerToken",
          "token":"access-token-from-Amazon"
       },
       "endpointId":"appliance-001"
    },
    "payload": {
      "type": "VALUE_OUT_OF_RANGE",
      "message": "色温度は500に設定できません".
      "validRange": {
        "minimumValue": 1000,
        "maximumValue": 10000
      }
    }
  }
}

TEMPERATURE_VALUE_OUT_OF_RANGEエラーの例

"event": {
    "header": {
      "namespace": "Alexa",
      "name": "ErrorResponse",
      "messageId": "a9a87be3-a41a-43c4-b734-04a8fcaf9d3c",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "BearerToken": "access-token-from-Amazon"
       },
       "endpointId" :  "<エンドポイントのエンドポイントID >" ,
    },
    "payload": {
      "type": "TEMPERATURE_VALUE_OUT_OF_RANGE",
      "message": "リクエストされた温度-15は範囲外です",
      "validRange": {
        "minimumValue": {
           "value": 15.0,
           "scale": "CELSIUS"
        },
        "maximumValue": {
           "value": 30.0,
           "scale": "CELSIUS"
        }
      }
    }
  }
}

その他のサンプルコード

リクエストと応答のサンプルについては、AlexaスマートホームのGitHubリポジトリで以下を参照してください。

ErrorResponse

インターフェース 説明
Alexa.Cooking.ErrorResponse 調理器具用に作成されたスキルに固有のエラーメッセージを定義します。
Alexa.Video.ErrorResponse ビデオスキルに固有のエラーメッセージを定義します。