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": "<エラーメッセージ>"
    }
  }
}

エラータイプの値

以下の表に有効なエラータイプを示します。

フィールド 説明
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
    }
  }
}
Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment