エラーと例外

このドキュメントでは、スマートホーム デバイスで公式にサポートされているエラーと例外を示します。これらのエラーコードと例外コードをインテント レスポンスまたは通知(実装している場合)で使用し、特定のコマンドやデバイスの状態に関連する問題を Google アシスタントがエンドユーザーにアラートで通知します。レスポンスに誤った形式や errorCode が含まれている場合、Google アシスタントはユーザーに一般的なエラー メッセージ(例: 「device は現在ご利用いただけません」)を返します。

エラー

問題が原因で実行リクエストまたはクエリ リクエストが失敗した場合は、エラーコードを返す必要があります。たとえば、ドアロックが引っかかり、ロックまたはロック解除できない場合は、この状態に関するエラーをユーザーに返します。

エラーコードは、デバイスレベルまたはグローバル レベルで添付できます。たとえば、ユーザーが 1 つのプロバイダが提供するライトを多数所有し、ハブによって制御されている場合、ユーザーがすべてのライトを消すように要求すると、プロバイダは 1 つのライトがオフラインの場合はデバイスレベルのエラーを返し、ハブ全体がオフラインになっていてライトを制御できない場合はグローバル レベルのエラーを返すことがあります。すべてのデバイスがオフラインの場合、グローバル レベルとデバイスレベルのエラーのどちらを使用するかに違いはありません。デバイスがオフラインのときは、deviceOffline エラーコードが返されても、reportState{"online": false} 状態を報告する必要があります。

手順は次のとおりです。

  • グローバル レベルのエラー: レスポンス内のすべてのデバイスに同じエラーがある
  • ローカルレベルのエラー: エラーと成功のケースを含むレスポンスが混在する

グローバル レベルのエラー

次の JSON スニペットは、QUERY レスポンスまたは EXECUTE レスポンスでグローバル レベルのエラーを返す方法を示しています。

ハブに起因するグローバル レベルのエラー deviceOffline の例は、オフラインです。

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "errorCode": "deviceOffline",
    "status" : "ERROR"
  }
}

ハブによるグローバル レベルのエラー inSoftwareUpdate の例は、更新中のものです。

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "errorCode": "inSoftwareUpdate",
    "status" : "ERROR"
  }
}

デバイスレベルのエラー

QUERY レスポンス

次の JSON スニペットは、QUERY レスポンスでデバイスレベルのエラーを返す方法を示しています。

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "device-id-1": {
        "errorCode": "deviceOffline",
        "status" : "ERROR"
      },
      "device-id-2": {
        "errorCode": "deviceOffline",
        "status" : "ERROR"
      }
    }
  }
}

EXECUTE レスポンス

次の JSON スニペットは、EXECUTE レスポンスでデバイスレベルのエラーを返す方法を示しています。

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "device-id-1"
        ],
        "status": "ERROR",
        "errorCode": "deviceOffline"
      },
      {
        "ids": [
          "device-id-2"
        ],
        "status": "SUCCESS",
        "states": {
          "on": true,
          "online": true
        }
      }
    ]
  }
}

エラーのある通知

パーソナル通知

次の JSON スニペットは、プロアクティブ通知でデバイスレベルのエラーを報告する方法を示しています。

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "agent-user-id-1",
  "eventId": "unique-event-id-1",
  "payload": {
    "devices": {
      "notifications": {
        "device-id-1": {
          "RunCycle": {
            "priority": 0,
            "status": "FAILURE",
            "errorCode": "deviceDoorOpen"
          }
        }
      }
    }
  }
}

フォローアップ対応

次の JSON スニペットは、フォローアップ レスポンスでデバイスレベルのエラーを報告する方法を示しています。

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "agentUserId": "agent-user-id-1",
  "eventId": "unique-event-id-1",
  "payload": {
    "devices": {
      "notifications": {
        "device-id-1": {
          "LockUnlock": {
            "priority": 0,
            "followUpResponse": {
              "status": "FAILURE",
              "errorCode": "deviceJammingDetected",
              "followUpToken": "PLACEHOLDER"
            }
          }
        }
      }
    }
  }
}

エラーリスト

次のエラーが発生すると、デバイスに関連する TTS が生成されます。

  • aboveMaximumLightEffectsDuration : 最大継続時間 1 時間を超えています。もう一度お試しください。
  • aboveMaximum タイマー Duration : <device(s)> を設定できるのは <time period> までです
  • actionNotAvailable : 申し訳ございません。現在、その操作はできないようです。
  • actionUnavailablewhileRunning : <device(s)> <is/are> は現在実行中であるため、変更できません。
  • すでに監視中 : <デバイス> は、すでに監視中です。
  • すでに AtMax : <device(s)> は、すでに最高温度に設定されています。
  • alreadyAtMin : <device(s)> は、すでに最低温度に設定されています。
  • alreadyClosed : <device(s)> <is/are> はすでにクローズされています。
  • 監視解除済み : <デバイス> の<is/are> はすでに解除されています。
  • 接続済み : <device(s)> は、すでにホルダーに装着されています。
  • alreadyInState : <device(s)> <is/are> はすでにその状態です。
  • すでにロックされています : <デバイス> はすでにロックされています。
  • すでにオフ : <device(s)> はすでにオフになっています。
  • オン : <デバイス> はすでにオンです。
  • alreadyOpen : <device(s)> <is/are> はすでに開いています。
  • alreadyPaused : <デバイス> <is/are> はすでに一時停止されています。
  • 開始済み : <device(s)> はすでに開始されています。
  • alreadyStopped : <device(s)> はすでに停止されています。
  • ロック解除済み : <device(s)> はすでにロック解除されています。
  • ambiguousZoneName : <device(s)> は、指定されたゾーンを識別できません。ゾーンに一意の名前を付けてから、もう一度お試しください。
  • amount aboveLimit : <device(s)> がサポートできる範囲を超えています。
  • appLaunchFailed : <デバイス> で <アプリ名> を起動できませんでした。
  • armFailure : <device(s)> は監視できませんでした。
  • armLevelNeeded : <device(s)> をどのレベルに設定すればよいかわかりません。「<デバイス> を <セキュリティ低> に設定して」または「<デバイス> を <高セキュリティ> に設定して」と言ってみてください。
  • authFailure : <device(s)> にアクセスできないようです。<デバイス/デバイス> のセットアップが完了していることをアプリでご確認ください。
  • bagFull : <device(s)> <has/have> <完全なバッグ/バッグ全体>。<it/them> を空にしてもう一度お試しください。
  • downMinimumLightEffectsDuration : 最小継続時間 5 分未満です。もう一度お試しください。
  • thanMinimum タイマー Duration : 長時間 <device(s)> を設定できません。もう一度お試しください。
  • binFull : <device(s)> <has/have> <完全なビン/完全なビン>。
  • cancelArmingRestricted : <device(s)> による監視をキャンセルできませんでした。
  • cancelTooLate : キャンセルの期限を過ぎています。代わりに <デバイス> またはアプリを使用してください。
  • channelSwitchFailed : チャンネル <チャンネル名> に切り替えられませんでした。しばらくしてからもう一度お試しください。
  • chargeIssue : 申し訳ありません、<device(s)> は <has/have> <acharger issue/charger issues> のようです。
  • commandInsertFailed : <device(s)> のコマンドを処理できません。
  • deadBattery : <デバイス>、<がある/ある> <バッテリー切れ/切れたバッテリー>。
  • degreeOutOfRange : リクエストされた角度は <device(s)> の範囲外です。
  • deviceAlertNeedsAssistance : <device(s)> にはアクティブなアラートがあり、あなたの支援は <need(s)> です。
  • deviceAtExtremeTemperature : <device(s)> は <an <an ご使用の物体温度> において <is/are> です。
  • device ビジー : <device(s)> ですぐになんらかの処理が進行中です。
  • deviceCharging : (ha_shared.ItsTheyre size=$item.devices.total_device_count)充電中のため、<device(s)> はその操作を行えません。
  • deviceClogged : <device(s)> が詰まっているようです。
  • deviceCurrentlyDispensing : <device(s)> は今、すでに何かを供給しています。
  • deviceDoorOpen : <device(s)> のドアが開いています。閉めてもう一度お試しください。
  • deviceHandleClosed : <device(s)> のハンドルが閉じています。ハンドルを開いて、もう一度お試しください。
  • deviceJammingDetected : <device(s)> <is/are> が故障しました。
  • deviceLidOpen : <device(s)> のカバーが開いています。閉じてから、もう一度お試しください。
  • deviceNeedsRepair : 修理が必要な<device(s)> <need(s)>。お近くのサービス ディーラーにお問い合わせください。
  • deviceNotDocked : 申し訳ありませんが、<device(s)> はホルダーに装着されていません。ホルダーにセットしてからもう一度お試しください。
  • deviceNotFound : <device(s)> は利用できません。<it/them> をもう一度設定してみてください。
  • deviceNotMounted : <it/they> が <is/are> マウントされていないため <device(s)> ではその操作を実行できないようです。
  • deviceNotReady : <device(s)> の準備ができていません。
  • deviceStuck : <device(s)> <is/are> が停止し、サポートが必要です。
  • deviceTampered : <device(s)> が改ざんされています。
  • deviceThermalShutdown 高温(または低温)のため <device(s)> がシャットダウンされたようです。
  • directResponseOnlyUnreachable : <device(s)> はリモコンをサポートしていません。
  • disarmFailure : <device(s)> の監視を解除できませんでした。
  • discreteOnlyOpenClose : <device(s)> は完全に開くか閉じることができます。
  • dispenseAmountAboveLimit : <device(s)> では大量の供給ができません。
  • dispenseAmountBelowLimit : <device(s)> では少量の供給ができません。
  • dispenseAmountRemainingExceeded : <device(s)> には、これを行うのに十分な <dispense item> がありません。
  • dispenseFractionalAmountNotSupported : <device(s)> は <dispense item> の小数点を供給できません。
  • dispenseFractionalUnitNotSupported : <device(s)> は <dispense item> のその単位の小数をサポートしていません。
  • dispenseUnitNotSupported : <device(s)> は <dispense item> のその単位をサポートしていません。
  • doorClosedTooLong : <device(s)> のドアが開いてからしばらく経過している。ドアを開けて、中にあるものがあることを確認してから、もう一度お試しください。
  • EmergencyHeatOn : <device(s)> は緊急ヒートモードになっているため、手動で調整する必要があります。
  • faultyBattery : <デバイス>、<ある/ある> <バッテリーの不良/不良のバッテリー>。
  • FloorUnreachable : <device(s)> はその部屋に到達できません。右側の階に移動してもう一度お試しください。
  • functionNotSupported : 実際には、<device(s)> はその機能をサポートしていません。
  • genericDispenseNotSupported : 何を供給するのか教えてください。アイテムの名前を入力して、もう一度お試しください。
  • ハードエラー : エラーが発生したため、スマートホーム デバイスを操作できません。
  • ハードエラー : エラーが発生したため、スマートホーム デバイスを操作できません。
  • inAutoMode : <device(s)> は、現在自動モードに設定されています。温度を変更するには、別のモードに切り替える必要があります。
  • inAwayMode : <device(s)> は現在、外出モードに設定されています。サーモスタットを操作するには、スマートフォン、タブレット、パソコンの Nest アプリを使用して手動で在宅モードに切り替える必要があります。
  • inDryMode : <device(s)> は除湿モードに設定されています。温度を変更するには、別のモードに切り替える必要があります。
  • inEcoMode : <device(s)> は、現在エコモードに設定されています。温度を変更するには、別のモードに切り替える必要があります。
  • inFanOnlyMode : <device(s)> は、現在ファン専用モードに設定されています。温度を変更するには、別のモードに切り替える必要があります。
  • inHeatOrCool : <device(s)> は暖房 / 冷房モードになっていません。
  • inHumidifierMode : <device(s)> は、現在加湿モードに設定されています。温度を変更するには、別のモードに切り替える必要があります。
  • inOffMode : <device(s)> は現在オフになっています。温度を変更するには、<it/them> を別のモードに切り替える必要があります。
  • inPurifierMode : <device(s)> は空気清浄モードに設定されています。温度を変更するには、別のモードに切り替える必要があります。
  • inSleepMode : <device(s)> はスリープモードです。しばらくしてからもう一度お試しください。
  • inSoftwareUpdate : <デバイス> はソフトウェア アップデート中です。
  • lockFailure : <device(s)> をロックできませんでした。
  • lockState : <デバイス> は現在ロックされています。
  • lockToRange : その温度は <device(s)> のロック範囲外です。
  • LowBattery : <device(s)> は <has/have> のバッテリー残量が少ない。
  • maxSettingReached : <デバイス> にはすでに最も高い設定が設定されています。
  • maxSpeedReached : <device(s)> はすでに最高速度に設定されています。
  • minSettingReached : <device(s)> は、すでに最低の設定に設定されています。
  • minSpeedReached : <device(s)> は最低速度に設定されています。
  • monitoringServiceConnectionLost : <デバイス> からモニタリング サービスへの接続が切断されました。
  • needAttachment : <device(s)> <is/are> に必要なアタッチメントがありません。取り付けてから、もう一度お試しください。
  • needBin : <device(s)> にビンがありません。取り付けてから、もう一度お試しください。
  • needPads : <device(s)> <need(s)> 個の新しいパッド。
  • needSoftwareUpdate : <デバイス> ソフトウェア アップデートを <必要>。
  • needWater : <device(s)> <need(s)> water.
  • networkProfileNotRecognized : <デバイス> で「<ネットワーク プロファイル>」を認識できません。
  • networkSpeedTestInProgress : <network> <speed/speeds>> はすでにテスト中です。
  • noAvailableApp : <アプリ名> は利用できないようです。
  • noAvailableChannel : チャンネル <チャンネル名> は利用できないようです。
  • noChannelSubscription : 現在、<チャンネル名> にはチャンネル登録していません。
  • no タイマー Exists : <device(s)> で設定済みのタイマーはありません。
  • サポート対象外 : <デバイス> ではそのモードを利用できません。
  • obstructionDetected : <device(s)> が障害物を検出しました。
  • オフライン 、 deviceOffline : 現在、<device(s)> は<is/are>ご利用いただけません。
  • onRequiresMode : オンにするモードを指定してください。
  • passphraseIncorrect : PIN が正しくないようです。
  • percentOutOfRange : <device(s)> を <percent> に設定することはできません。
  • pinIncorrect : (passphraseIncorrect)
  • rainDetected : 雨が検知されたため、<device(s)> を開かませんでした。
  • rangeTooClose : <device(s)> の暖房・冷房範囲に対して近すぎます。もっと差のある温度を選択してください。
  • relinkRequired : ご利用のアカウントで問題が発生しているようです。Google Home アプリまたはアシスタント アプリを使用して <デバイス> を再リンクしてください。
  • remoteSetDisabled :
    • 省略可能なパラメータ errorCodeReason
    • currentlyArmed - 申し訳ございません。すでにセキュリティ システムにより監視中です。変更を行うには <デバイス> またはアプリを使用する必要があります。
    • remoteUnlockNotAllowed - リモートでは <device(s)> のロックを解除できません。
    • remoteControlOff - そのアクションは現在無効になっています。<デバイス> でリモコンを有効にしてから、もう一度お試しください。
    • childSafetyModeActive - 子どものセーフモードが有効な間、<device(s)> ではその操作は無効になります。
  • roomOnDifferentFloors : <device(s)> は別の階にあるため、この部屋に到達できません。
  • safetyShutOff : <device(s)> は緊急遮断モードになっているため、<it/they> は手動で調整する必要があります。
  • sceneCannotBeApplied : <device(s)> を適用できません。
  • securityRestriction : <デバイス> にセキュリティ制限が <あります>。
  • softwareUpdateNotAvailable : <device(s)> で利用可能なソフトウェア アップデートはありません。
  • startRequiresTime : その操作を行うには、<device(s)> の稼働時間を指定してください。
  • tillCoolingDown : <device(s)> はまだ冷房中です。
  • tillWarmingUp : <device(s)> はまだウォームアップ中です。
  • streamUnavailable : 現在 <デバイス> からのストリームを利用できないようです。
  • streamUnplayable : 現在、<device(s)> でストリーミングを再生できません。
  • tankEmpty : <device(s)> に <空のタンク / 空のタンク> があります。<it/them> を入力して、もう一度お試しください。
  • targetAlreadyReached :
  • triggerValueOutOfRange : その時間の間は <device(s)> を設定できません。
  • too ManyFailedAttempts : 試行の回数が多すぎます。デバイスのアプリでそのアクションを完了してください。
  • transientError : <device(s)> の操作でエラーが発生しました。もう一度お試しください。
  • turnOff 、deviceTurnedOff : 現在、<device(s)> はオフになっています。
  • unavailableToFindingDevice : <device(s)> が見つかりませんでした。
  • ununknownFoodPreset : <device(s)> はそのフード プリセットをサポートしていません。
  • unlockFailure : <device(s)> のロックを解除できませんでした。
  • unpausableState : 現在、<device(s)> を一時停止できません。
  • userCancelled : OK
  • valueOutOfRange : <device(s)> をその温度に設定することはできません。

例外

コマンドに関連する問題やアラートがある場合は、例外を返す必要があります。コマンドは成功または失敗する可能性があります。

コマンドが成功した場合(ステータス = "SUCCESS")、例外を報告するには、StatusReport トレイト(対象以外のデバイスの場合)を使用するか、(対象デバイスの場合)適切な exceptionCode を返します。

たとえば、ドライヤーの lint スクリーンがいっぱいの場合でも、ユーザーはドライヤーを起動できますが、この状態について警告する必要があるかもしれません。同様に、デバイスのバッテリー残量が低下していて空でない場合も、コマンドは実行できますが、デバイスのバッテリー残量が少ないことをユーザーに通知する必要があります。

例外が原因でコマンドが失敗した場合、ステータスは「EXCEPTIONS」になります。例外は StatusReport トレイトを使用して報告します。

対象デバイスに関する非ブロック例外(SUCCESS)

これはドアをロックする場合の例です。

正面玄関のロックのバッテリー残量が少なくなっています。玄関のドアをロックします。

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["device-id-1"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true,
        "isLocked": true,
        "isJammed": false,
        "exceptionCode": "lowBattery"
      }
    }]
  }
}

StatusReport を使用する別のデバイスに関する非ブロック例外(SUCCESS)

この例は、セキュリティ システムを作動させる場合の例です。「OK、セキュリティ システムを作動させます。正面の窓は開いています。

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["device-id-1"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true,
        "isArmed": true,
        "currentArmLevel": "L2",
        "currentStatusReport": [{
          "blocking": false,
          "deviceTarget": "sensor_id1",
          "priority": 0,
          "statusCode": "deviceOpen"
        }]
      }
    }]
  }
}

StatusReport を使用する別のデバイスに関するブロック例外

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "device-id-1": {
        "on": true,
        "online": true,
        "status": "EXCEPTIONS",
        "currentStatusReport": [{
            "blocking": true,
            "deviceTarget": "device-id-1",
            "priority": 0,
            "statusCode": "lowBattery"
          },
          {
            "blocking": true,
            "deviceTarget": "front_window_id",
            "priority": 1,
            "statusCode": "deviceOpen"
          },
          {
            "blocking": true,
            "deviceTarget": "back_window_id",
            "priority": 1,
            "statusCode": "deviceOpen"
          }
        ]
      }
    }
  }
}

例外リスト

次の例外がある場合、デバイスに関連する TTS が生成されます。

  • bagFull : <device(s)> <has/have> <完全なバッグ/バッグ全体>。<it/them> を空にしてもう一度お試しください。
  • binFull : <device(s)> <has/have> <完全なビン/完全なビン>。
  • curveMonoxideDetected : <家名> で一酸化炭素が検出されました。
  • deviceAtExtremeTemperature : <device(s)> は <an <an ご使用の物体温度> において <is/are> です。
  • deviceJammingDetected : <device(s)> <is/are> が故障しました。
  • deviceMoved : <device(s)> が <was/were> を移動しました。
  • deviceOpen : <device(s)> が開いています。
  • deviceTampered : <device(s)> が改ざんされています。
  • deviceUnjectged : <device(s)> が電源から外されました。
  • FloorUnreachable : <device(s)> はその部屋に到達できません。右側の階に移動してもう一度お試しください。
  • HardwareFailure : <デバイス> にハードウェアの問題があります。
  • inSoftwareUpdate : <デバイス> はソフトウェア アップデート中です。
  • isBypassed : <device(s)> は、現在バイパスされています。
  • LowBattery : <device(s)> は <has/have> のバッテリー残量が少ない。
  • motionDetected : <device(s)> <detect(s)> モーション。
  • needPads : <device(s)> <need(s)> 個の新しいパッド。
  • needSoftwareUpdate : <デバイス> ソフトウェア アップデートを <必要>。
  • needWater : <device(s)> <need(s)> water.
  • networkJammingDetected : <device(s)> へのホーム ネットワーク接続が正常に動作していません。
  • noIssuesReported : <device(s)> で問題は報告されていません。
  • roomOnDifferentFloors : <device(s)> は別の階にあるため、この部屋に到達できません。
  • runCycleFinished : <device(s)> は <has/have> のランニングを終了しました。
  • securityRestriction : <デバイス> にセキュリティ制限が <あります>。
  • smokeDetected : <家名> で煙が検知されました。
  • tankEmpty : <device(s)> に <空のタンク / 空のタンク> があります。<it/them> を入力して、もう一度お試しください。
  • usingCellularBackup : <デバイス> <が>(遠隔バックアップを使用)。
  • waterLeakDetected : 水漏れを <device(s)> <detect(s)> 検出。