ErrorResponse

Note: Register now for Alexa Live, Amazon’s annual Alexa developer conference on July 20, 2022.

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
    }
  }
}

ErrorResponse

エラー応答イベント

エラータイプの値

例

関連トピック