Alexa.ErrorResponseインターフェース 3

Alexa.ErrorResponseインターフェース 3

Alexaからスキルに送られたリクエストを正常に処理できない場合は、Alexa.ErrorResponseイベントを返します。エラータイプとその理由を指定してください。応答は同期または非同期のどちらでも可能です。非同期で応答する場合、相関トークンと、認可トークンを含めたスコープを含めます。

エラータイプの値に記載されている一般的なエラーには、Alexa.ErrorResponseイベントを使用します。必要に応じて、次のいずれかのより具体的なエラーイベントを代わりに使用します：

ディレクティブを正常に処理できなかった場合は、代わりにAlexa.Responseイベントを使用して応答します。

ErrorResponseイベント

Alexa.ErrorResponseのペイロードには、エラータイプを指定し、エラー情報のメッセージを含めます。エラータイプの一覧については、エラータイプの値を参照してください。

ErrorResponseイベントの形式

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ErrorResponse",
      "messageId": "一意の識別子、バージョン4 UUIDが望ましい",
       "correlationToken": "リクエストに一致するopaque相関トークン",
      "payloadVersion": "3"
    },
    "endpoint":{
      "endpointId": "エンドポイントID"
    },
    "payload": {
      "type": "エラータイプ",
      "message": "エラーメッセージ"
    }
  }
}

同期的なErrorResponse

Lambda関数からディレクティブに応答する場合、同期応答を送信します。ディレクティブのリクエストの値を設定したcorrelationTokenを含めます。

以下は、Alexaに同期的に送信するエラー応答の例です。エラータイプの一覧については、エラータイプの値を参照してください。

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ErrorResponse",
      "messageId": "一意の識別子、バージョン4 UUIDが望ましい",
      "correlationToken": "リクエストに一致するopaque相関トークン",
      "payloadVersion": "3"
    },
    "endpoint":{
      "endpointId": "エンドポイントID"
    },
    "payload": {
      "type": "ENDPOINT_UNREACHABLE",
      "message": "エンドポイント12345にアクセスできません。オフラインの可能性があります"
    }
  }
}

非同期的なErrorResponse

デバイス制御クラウドからディレクティブに応答する場合、Alexaイベントゲートウェイに非同期応答を送信します。相関トークンと、認可トークンを含めたスコープを含めます。詳細については、イベントゲートウェイにイベントを送信するを参照してください。非同期のAlexa.ErrorResponseをゲートウェイに送信する際、Alexaは成功か失敗かを示すHTTPステータスコードを送信します。

以下は、Alexaイベントゲートウェイに非同期的に送信するエラー応答の例です。エラータイプの一覧については、エラータイプの値を参照してください。

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ErrorResponse",
      "messageId": "一意の識別子、バージョン4 UUIDが望ましい",
      "correlationToken": "リクエストに一致するopaque相関トークン",
      "payloadVersion": "3"
    },
    "endpoint":{
      "scope":{
        "type":"BearerToken",
        "token":"access-token-from-Amazon"
      },
      "endpointId": "エンドポイントID"
    },
    "payload": {
      "type": "ENDPOINT_UNREACHABLE",
      "message": "エンドポイント12345にアクセスできません。オフラインの可能性があります。"
    }
  }
}

HTTPステータスコード

次の表は、スキルがAlexaイベントゲートウェイから受け取る可能性のあるHTTPステータスコードの一覧です。エラーを受け取った場合は、payloadオブジェクトにcodeフィールドとdescriptionフィールドが含まれます。これらのフィールドはログ記録の目的でのみ使用してください。

ステータス ペイロードのコード 説明

202 Accepted

—

リクエストは認可され、メッセージは構文的に有効なイベントでした。イベントは受け付けられ、論理的な検証と処理に進みます。

400 Bad Request

INVALID_REQUEST_EXCEPTION

メッセージが無効です。フィールドがない、値が正しくない、正しいJSON形式ではないことが原因です。ドキュメントと照合して、メッセージにすべての必須フィールドが含まれていることを確認します。

401 Unauthorized

INVALID_ACCESS_TOKEN_EXCEPTION

メッセージに認可トークンが含まれていないか、トークンが無効、有効期限切れ、形式が正しくないのいずれかです。トークンを更新して、リクエストを再試行してください。ユーザーがスキルを無効にすると、アクセストークンも無効になります。この場合は、ユーザーが認可を取り消したため、変更レポートの送信も停止できます。

403 Forbidden

SKILL_NEVER_ENABLED_EXCEPTION

イベントゲートウェイへのアクセスが許可されていません。イベントを正しいリージョンのエンドポイントに送信していることを確認してください。たとえば、北米のイベントは北米のエンドポイントに送信します。

403 Forbidden

INSUFFICIENT_PERMISSION_EXCEPTION

トークンに必要な権限がありません。スキルにAlexaイベントを送信する権限があることを確認してください。詳細については、Alexaイベントゲートウェイへのアクセス権限のリクエストを参照してください。

404 Not Found

ACCOUNT_NOT_FOUND_EXCEPTION

指定されたIDに関連付けられたアカウントレコードが存在しないか、期限が切れています。このエラーは、イベントの送信が遅すぎた場合や、無効なIDが指定された場合に発生する可能性があります。指定されたIDと認可コードが正しいことを確認してください。

404 Not Found

SKILL_NOT_FOUND_EXCEPTION

このトークンに関連付けられたスキルIDが見つかりませんでした。このエラーは、スキルが認定中などの異なるステージにある状況でユーザーのアクセストークンが生成された場合に発生します。このユーザーでスキルの無効化と有効化を行ってみてください。

413 Payload Too Large

REQUEST_ENTITY_TOO_LARGE_EXCEPTION

イベントペイロードのサイズが大きすぎます。1回のリクエストで許容されるエンドポイントの最大数は300です。より小さいペイロードでメッセージを送信してください。

429 Too Many Requests

THROTTLING_EXCEPTION

リクエスト数が多すぎます。メッセージを再送してください。ただし、再送は最大3回までで、再送の間隔は1秒以上空けてください。

500 Internal Server Error

INTERNAL_SERVICE_EXCEPTION

Alexaでエラーが発生したため、メッセージは処理されませんでした。メッセージを再送してください。ただし、再送は最大3回までで、再送の間隔は1秒以上空けてください。問題が解消されない場合、Alexa開発者向け問い合わせ窓口にお問い合わせください。

503 Service Unavailable

SERVICE_UNAVAILABLE_EXCEPTION

Alexaがメッセージを受け取れませんでした。メッセージを再送してください。ただし、再送は最大3回までで、再送の間隔は1秒以上空けてください。問題が解消されない場合、Alexa開発者向け問い合わせ窓口にお問い合わせください。

応答本文401 Unauthorizedの例

以下は、エラー応答の例です。

HTTP/1.1 400 Bad Request
Date: Wed, 07 Mar 2018 20:25:31 GMT
Connection: close

{
  "header": {
    "namespace": "System",
    "name": "Exception",
    "messageId": "90c3fc62-4b2d-460c-9c8b-77251f1698a0"
  },
  "payload": {
      "code": "INVALID_ACCESS_TOKEN_EXCEPTION",
      "description": "アクセストークンが無効、有効期限切れ、形式が正しくないのいずれかです。"
  }
}

ErrorResponseイベントのペイロードのプロパティ

EventオブジェクトでAlexa.ErrorResponseを送信します。event.payloadパラメーターに以下の情報を含めます。

プロパティ 説明 型 必須

type

エラーのタイプです。Alexaはこれをユーザーと共有します。

文字列

◯

message

エラーを説明するメッセージです。この情報はユーザーには共有されません。

文字列

◯

エラータイプの値

以下の表に有効なエラータイプを示します。エラータイプが異なる場合、必ずしもAlexaが異なる応答を発話するとは限りません。

フィールド 説明
ALREADY_IN_OPERATION エンドポイントがすでに稼動中であるため、リクエストされた処理を実行できません。
BRIDGE_UNREACHABLE ブリッジが到達できない状態であるか、オフラインになっています。たとえば、ブリッジがオフになっている、ユーザーのローカルエリアネットワークから切断されている、ブリッジとデバイス制御クラウドの間の接続が切断されているなどです。ReportStateディレクティブに応答するときに、このエラーではなくStateReportを返す必要が生じるケースがあります。詳細については、Alexa.EndpointHealthを参照してください。
CLOUD_CONTROL_DISABLED ユーザーはインターネット経由でデバイスを制御できません。代わりに手動でデバイスを制御する必要があります。
ENDPOINT_BUSY エンドポイントが別のアクションを実行中のため、ディレクティブを処理できません。アクションは、Alexaへのリクエストや手動の操作の可能性があります。
ENDPOINT_CONTROL_UNAVAILABLE たとえば、自動車に接続されていないなどの理由で、現在エンドポイントを制御できません。コネクテッドカーの接続に問題がある場合は、このエラータイプを使用します。
このエラー応答を送信する際、ペイロードに、制御ができないことを示す理由を含めます。例については、ENDPOINT_CONTROL_UNAVAILABLEを参照してください。
ENDPOINT_LOW_POWER エンドポイントのバッテリー残量が足りないため、ディレクティブを処理できません。こちらの例を参照してください。
ENDPOINT_UNREACHABLE エンドポイントが到達できない状態であるか、オフラインになっています。たとえば、エンドポイントがオフになっている、ユーザーのローカルエリアネットワークから切断されている、エンドポイントとブリッジまたはエンドポイントとデバイス制御クラウドの間の接続が切断されているなどです。ReportStateディレクティブに応答するときに、このエラーではなくStateReportを返す必要が生じるケースがあります。詳細については、Alexa.EndpointHealthを参照してください。
EXPIRED_AUTHORIZATION_CREDENTIAL Alexaが提供する認可資格情報が期限切れです。ユーザーのOAuth2.0アクセストークンが期限切れになっている場合などです。
FIRMWARE_OUT_OF_DATE エンドポイントのファームウェアが期限切れになっているため、ディレクティブを処理できません。
HARDWARE_MALFUNCTION エンドポイントでハードウェアの故障が発生したため、ディレクティブを処理できません。
INSUFFICIENT_PERMISSIONS Alexaには、指定されたアクションをエンドポイントで実行する権限がありません。
INTERNAL_ERROR ほかのエラータイプでは説明できないエラーが発生しました。ランタイム例外が発生した場合などがこれにあたりますが、可能な場合は、常に具体的なエラータイプを送信することを推奨します。
INVALID_AUTHORIZATION_CREDENTIAL Alexaが提供する認可資格情報が無効です。たとえば、ユーザーのデバイス制御クラウドアカウントでOAuth2.0アクセストークンが有効でない場合などです。
INVALID_DIRECTIVE ディレクティブがこのスキルでサポートされていないか、正しくありません。
INVALID_VALUE ディレクティブに、ターゲットとするエンドポイントでは無効の値が含まれています。たとえば、暖房モード、チャンネル値、プログラム値などが無効の場合です。
NO_SUCH_ENDPOINT エンドポイントが存在しない、または存在しなくなりました。
NOT_CALIBRATED エンドポイントが較正中（暖機中など）のため、またはデバイスでまだユーザー設定が行われていないため、ディレクティブを処理できません。
NOT_IN_OPERATION エンドポイントが稼動していません。たとえば、スマートホームスキルがRESUMEディレクティブを受け取ったけれど、エンドポイントがOFFモードの場合、NOT_IN_OPERATIONエラーを返すことができます。
NOT_SUPPORTED_IN_CURRENT_MODE 現在の操作モードが原因で、エンドポイントはデバイスを指定された値に設定できません。このエラー応答を送信する場合は、デバイスを新しい値に設定できない理由を示すcurrentDeviceModeフィールドをペイロードに含めてください。有効な値は、COLOR、ASLEEP、NOT_PROVISIONED、OTHERです。こちらの例を参照してください。
NOT_SUPPORTED_WITH_CURRENT_BATTERY_CHARGE_STATE 現在のバッテリー状態では、エンドポイントはリクエストを実行できません。このエラー応答を送信する場合は、バッテリーの状態を示すcurrentChargeStateプロパティをペイロードに含めてください。任意で、バッテリーレベルをパーセンテージで示すCurrentChargeLevelInPercentageプロパティを含めることもできます。こちらの例を参照してください。
PARTNER_APPLICATION_REDIRECTION エンドポイントはリクエストを処理できません。このエラーを受信すると、Alexaはユーザーにパートナーアプリを確認するようプロンプトを出します。
POWER_LEVEL_NOT_SUPPORTED エンドポイントがサポートしていない電力レベルの操作がリクエストされたため、ディレクティブを処理できません。
RATE_LIMIT_EXCEEDED リクエストは、エンドポイントまたはブリッジがディレクティブを処理できる最大レートを超えています。
TEMPERATURE_VALUE_OUT_OF_RANGE 許容される温度の範囲外であるため、エンドポイントを指定された値に設定できません。このエラー応答を送信する場合は、オプションとして、有効な温度範囲を示すvalidRangeオブジェクトをペイロードに含めることができます。こちらの例を参照してください。
TOO_MANY_FAILED_ATTEMPTS パスワード入力時などに許容される失敗回数を超えています。
VALUE_OUT_OF_RANGE 許容される数値の範囲外であるため、エンドポイントを指定された値に設定できません。たとえば、ユーザーが100を超えるパーセンテージ値をリクエストした場合にこのエラーを使用できます。温度値には、代わりにTEMPERATURE_VALUE_OUT_OF_RANGEを使用します。このエラー応答を送信する場合は、オプションとして、有効な数値範囲を示すvalidRangeオブジェクトをペイロードに含めることができます。こちらの例を参照してください。

ErrorResponseの例

以下の例は、さまざまなエラータイプのペイロードを示しています。

ENDPOINT_CONTROL_UNAVAILABLE

以下は、ENDPOINT_CONTROL_UNAVAILABLEエラータイプのエラー応答の例です。制御できない理由を示すreason文字列をペイロードに含めます。エラータイプの一覧については、エラータイプの値を参照してください。

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ErrorResponse",
      "messageId": "一意の識別子、バージョン4 UUIDが望ましい",
       "correlationToken": "リクエストに一致するopaque相関トークン",
      "payloadVersion": "3"
    },
    "endpoint":{
      "endpointId": "エンドポイントID"
    },
    "payload": {
      "type": "ENDPOINT_CONTROL_UNAVAILABLE",
      "message": "車の接続パッケージが有効になっていません。",
      "reason": "NO_CONNECTIVITY_PACKAGE_ENABLED"
    }
  }
}

ENDPOINT_LOW_POWER

以下は、ENDPOINT_LOW_POWERエラータイプのエラー応答の例です。

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ErrorResponse",
      "messageId": "一意の識別子、バージョン4 UUIDが望ましい",
      "correlationToken": "リクエストに一致するopaque相関トークン",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "エンドポイントID"
    },
    "payload": {
      "type": "ENDPOINT_LOW_POWER",
      "message": "ロックのバッテリー残量が足りません",
      "percentageState": 5
    }
  }
}

NOT_SUPPORTED_IN_CURRENT_MODE

以下は、NOT_SUPPORTED_IN_CURRENT_MODEエラータイプのエラー応答の例です。

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa.ColorTemperatureController",
      "name": "ErrorResponse",
      "messageId": "一意の識別子、バージョン4 UUIDが望ましい",
      "correlationToken": "リクエストに一致するopaque相関トークン",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "エンドポイントID"
    },
    "payload": {
      "type": "NOT_SUPPORTED_IN_CURRENT_MODE",
      "message": "照明は現在、カラーに設定されています。",
      "currentDeviceMode": "COLOR"
    }
  }
}

NOT_SUPPORTED_WITH_CURRENT_BATTERY_CHARGE_STATE

以下は、NOT_SUPPORTED_WITH_CURRENT_BATTERY_CHARGE_STATEエラータイプのエラー応答の例です。

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ErrorResponse",
      "messageId": "一意の識別子、バージョン4 UUIDが望ましい",
      "correlationToken": "リクエストに一致するopaque相関トークン",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "エンドポイントID"
    },
    "payload": {
      "type": "NOT_SUPPORTED_WITH_CURRENT_BATTERY_CHARGE_STATE ",
      "message":"車は充電されていました",
      "currentChargeState": "ALREADY_CHARGED_TO_REQUIRED_LEVEL",
      "currentChargeLevelInPercentage": 75
    }
  }
}

TEMPERATURE_VALUE_OUT_OF_RANGE

以下は、TEMPERATURE_VALUE_OUT_OF_RANGEエラータイプのエラー応答の例です。設定可能な最小および最高温度を示すvalidRangeオブジェクトをペイロードに含めます。

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ErrorResponse",
      "messageId": "一意の識別子、バージョン4 UUIDが望ましい",
      "correlationToken": "リクエストに一致するopaque相関トークン",
      "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"
        }
      }
    }
  }
}

VALUE_OUT_OF_RANGE

以下は、VALUE_OUT_OF_RANGEエラータイプのエラー応答の例です。設定可能な最小および最高の値を示すvalidRangeオブジェクトをペイロードに含めます。

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ErrorResponse",
      "messageId": "一意の識別子、バージョン4 UUIDが望ましい",
      "correlationToken": "リクエストに一致するopaque相関トークン",
      "payloadVersion": "3"
    },
    "endpoint":{
      "endpointId": "エンドポイントID"
    },
    "payload": {
      "type": "VALUE_OUT_OF_RANGE",
      "message": "100を超えるパーセンテージ値は設定できません。",
      "validRange": {
        "minimumValue": 0,
        "maximumValue": 100
      }
    }
  }
}

プロパティとオブジェクト

一部のエラータイプでは、ペイロードに次のオブジェクトが含まれます。詳細については、エラータイプの値を参照してください。

CurrentChargeLevelInPercentageプロパティ

NOT_SUPPORTED_WITH_CURRENT_BATTERY_CHARGE_STATEエラー応答を送信する際は、currentChargeLevelInPercentageプロパティをペイロードに含めます。currentChargeLevelInPercentageは、バッテリーレベルをパーセンテージで示します。有効な値は、 0～100です。このプロパティはオプションです。

以下の例は、CurrentChargeLevelInPercentageプロパティの例を示しています。

クリップボードにコピーされました。

{
  "currentChargeLevelInPercentage": "100"
}

CurrentChargeStateプロパティ

NOT_SUPPORTED_WITH_CURRENT_BATTERY_CHARGE_STATEエラー応答を送信する際は、currentChargeStateプロパティをペイロードに含めます。currentChargeStateは、バッテリーの現在の状態を示します。

以下の表は、バッテリー状態の有効な値を示しています。

バッテリー状態 説明

ALREADY_CHARGED_TO_REQUIRED_LEVEL

車のバッテリーレベルはリクエストされたレベルより高いです。

CURRENTLY_CHARGING

車のバッテリーは充電中です。

FULLY_CHARGED

車のバッテリーレベルは100%です。

NOT_CONNECTED_TO_POWER

車のバッテリーが充電器に接続されていません。

理由の値

ENDPOINT_CONTROL_UNAVAILABLEエラー応答を送信する際は、エンドポイントを制御できない理由を示すreason文字列をペイロードに含めます。

プロパティ 説明

DEEP_SLEEP_MODE

ディープスリープモードは、コネクテッドカーなどのエンドポイントのユーザー定義の設定です。ユーザーは、このモードをオフにすることで、この問題を解決できる可能性があります。

OUT_OF_NETWORK_CONNECTIVITY

エンドポイントは、ネットワーク接続サービスの範囲外にあります。

NO_CONNECTIVITY_PACKAGE_ENABLED

エンドポイントを利用するには、ユーザーがインターネットプランを購入するか有効にする必要があります。

UNKNOWN

不明な理由により、デバイス制御クラウドがエンドポイントに接続できません。

ValidRangeオブジェクト

VALUE_OUT_OF_RANGEエラー応答を送信する際は、設定可能な最小および最大の値を示すvalidRangeオブジェクトをペイロードに含めます。このプロパティはオプションです。

以下は、ValidRangeオブジェクトの例です。

クリップボードにコピーされました。

{
  "validRange": {
    "minimumValue": 0,
    "maximumValue": 100
  }
}

温度を含むValidRangeオブジェクト

TEMPERATURE_VALUE_OUT_OF_RANGEエラー応答を送信する際は、設定可能な最小および最大の温度を示すvalidRangeオブジェクトをペイロードに含めます。最大値と最小値は、temperatureオブジェクトを含みます。このプロパティはオプションです。

以下は、温度を指定したValidRangeオブジェクトの例です。

クリップボードにコピーされました。

{
  "validRange": {
    "minimumValue": {
      "value": 15.0,
      "scale": "CELSIUS"
    },
    "maximumValue": {
      "value": 30.0,
      "scale": "CELSIUS"
    }
  }
}