Alexa.ErrorResponseインターフェース 3
Alexaからスキルに送られたリクエストを正常に処理できない場合は、Alexa.ErrorResponseイベントを返します。エラータイプとその理由を指定してください。応答は同期または非同期のどちらでも可能です。非同期で応答する場合、相関トークンと、認可トークンを含めたスコープを含めます。
エラータイプの値に記載されている一般的なエラーには、Alexa.ErrorResponseイベントを使用します。必要に応じて、次のいずれかのより具体的なエラーイベントを代わりに使用します：
Alexa.AuthorizationController.ErrorResponseAlexa.Commissionable.ReportCommissioningInformation.ErrorResponseAlexa.Cooking.ErrorResponseAlexa.DataController.ErrorResponseAlexa.Safety.ErrorResponseAlexa.SecurityPanelController.ErrorResponseAlexa.ThermostatController.Configuration.ErrorResponseAlexa.ThermostatController.ErrorResponseAlexa.ThermostatController.Schedule.ErrorResponseAlexa.Video.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フィールドが含まれます。これらのフィールドはログ記録の目的でのみ使用してください。
| ステータス | ペイロードのコード | 説明 |
|---|---|---|
|
|
— |
リクエストは認可され、メッセージは構文的に有効なイベントでした。イベントは受け付けられ、論理的な検証と処理に進みます。 |
|
|
|
メッセージが無効です。フィールドがない、値が正しくない、正しいJSON形式ではないことが原因です。ドキュメントと照合して、メッセージにすべての必須フィールドが含まれていることを確認します。 |
|
|
|
メッセージに認可トークンが含まれていないか、トークンが無効、有効期限切れ、形式が正しくないのいずれかです。トークンを更新して、リクエストを再試行してください。ユーザーがスキルを無効にすると、アクセストークンも無効になります。この場合は、ユーザーが認可を取り消したため、変更レポートの送信も停止できます。 |
|
|
|
イベントゲートウェイへのアクセスが許可されていません。イベントを正しいリージョンのエンドポイントに送信していることを確認してください。たとえば、北米のイベントは北米のエンドポイントに送信します。 |
|
|
|
トークンに必要な権限がありません。スキルにAlexaイベントを送信する権限があることを確認してください。詳細については、Alexaイベントゲートウェイへのアクセス権限のリクエストを参照してください。 |
|
|
|
指定されたIDに関連付けられたアカウントレコードが存在しないか、期限が切れています。このエラーは、イベントの送信が遅すぎた場合や、無効なIDが指定された場合に発生する可能性があります。指定されたIDと認可コードが正しいことを確認してください。 |
|
|
|
このトークンに関連付けられたスキルIDが見つかりませんでした。このエラーは、スキルが認定中などの異なるステージにある状況でユーザーのアクセストークンが生成された場合に発生します。このユーザーでスキルの無効化と有効化を行ってみてください。 |
|
|
|
イベントペイロードのサイズが大きすぎます。1回のリクエストで許容されるエンドポイントの最大数は300です。より小さいペイロードでメッセージを送信してください。 |
|
|
|
リクエスト数が多すぎます。メッセージを再送してください。ただし、再送は最大3回までで、再送の間隔は1秒以上空けてください。 |
|
|
|
Alexaでエラーが発生したため、メッセージは処理されませんでした。メッセージを再送してください。ただし、再送は最大3回までで、再送の間隔は1秒以上空けてください。問題が解消されない場合、Alexa開発者向け問い合わせ窓口にお問い合わせください。 |
|
|
|
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パラメーターに以下の情報を含めます。
| プロパティ | 説明 | 型 | 必須 |
|---|---|---|---|
|
|
エラーのタイプです。Alexaはこれをユーザーと共有します。 |
文字列 |
◯ |
|
|
エラーを説明するメッセージです。この情報はユーザーには共有されません。 |
文字列 |
◯ |
エラータイプの値
以下の表に有効なエラータイプを示します。エラータイプが異なる場合、必ずしも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文字列をペイロードに含めます。エラータイプの一覧については、エラータイプの値を参照してください。
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は、バッテリーの現在の状態を示します。
以下の表は、バッテリー状態の有効な値を示しています。
| バッテリー状態 | 説明 |
|---|---|
|
|
車のバッテリーレベルはリクエストされたレベルより高いです。 |
|
|
車のバッテリーは充電中です。 |
|
|
車のバッテリーレベルは100%です。 |
|
|
車のバッテリーが充電器に接続されていません。 |
理由の値
ENDPOINT_CONTROL_UNAVAILABLEエラー応答を送信する際は、エンドポイントを制御できない理由を示すreason文字列をペイロードに含めます。
| プロパティ | 説明 |
|---|---|
|
|
ディープスリープモードは、コネクテッドカーなどのエンドポイントのユーザー定義の設定です。ユーザーは、このモードをオフにすることで、この問題を解決できる可能性があります。 |
|
|
エンドポイントは、ネットワーク接続サービスの範囲外にあります。 |
|
|
エンドポイントを利用するには、ユーザーがインターネットプランを購入するか有効にする必要があります。 |
|
|
不明な理由により、デバイス制御クラウドがエンドポイントに接続できません。 |
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"
}
}
}
関連トピック
- Alexa.AuthorizationController.ErrorResponse
- Alexa.Cooking.ErrorResponse
- Alexa.DataController.ErrorResponse
- Alexa.Safety.ErrorResponse
- Alexa.SecurityPanelController.ErrorResponse
- Alexa.SmartVision.ObjectDetectionSensor.ErrorResponse
- Alexa.ThermostatController.ErrorResponse
- Alexa.ThermostatController.Configuration.ErrorResponse
- Alexa.ThermostatController.Schedule.ErrorResponse
- Alexa.Video.ErrorResponse
最終更新日: 2022 年 12 月 02 日