エラーと例外

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

エラー

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

エラーコードは、デバイスレベルまたはグローバル レベルで付加できます。たとえば、ユーザーが 1 つのプロバイダの照明を多数所有しており、それらがハブで制御されている場合、ユーザーがすべての照明をオフにするようリクエストすると、1 つの照明がオフラインの場合はデバイスレベルのエラーが、ハブ全体がオフラインで照明を制御できない場合はグローバル レベルのエラーが返されることがあります。すべてのデバイスがオフラインの場合、グローバル レベルのエラーとデバイスレベルのエラーの使用に違いはありません。

概要は次のとおりです。

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

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

次の 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 時間です。もう一度お試しください。
  • aboveMaximumTimerDuration : <デバイス> のタイマーを <期間> までしか設定できません
  • actionNotAvailable : 現在、その操作は行えません。
  • actionUnavailableWhileRunning : <デバイス> は現在実行中のため、変更できません。
  • alreadyArmed : <デバイス> はすでに監視中です。
  • alreadyAtMax : <デバイス> はすでに最高温度に設定されています。
  • alreadyAtMin : <デバイス> はすでに最低温度に設定されています。
  • alreadyClosed : <デバイス> はすでに閉じられています。
  • alreadyDisarmed : <デバイス> はすでに解除されています。
  • alreadyDocked : <デバイス> はすでにドッキングされています。
  • alreadyInState : <デバイス> はすでにその状態です。
  • alreadyLocked : <デバイス> はすでにロックされています。
  • alreadyOff : <デバイス> はすでにオフになっています。
  • alreadyOn : <デバイス> はすでにオンになっています。
  • alreadyOpen : <device(s)> <is/are> already open.(<デバイス> はすでに開いています)。
  • alreadyPaused : <デバイス> はすでに一時停止されています。
  • alreadyStarted : <デバイス> はすでに起動しています。
  • alreadyStopped : <デバイス> はすでに停止しています。
  • alreadyUnlocked : <デバイス> はすでにロック解除されています。
  • ambiguousZoneName : 申し訳ありませんが、<デバイス> をかける場所がわかりません。固有の名前をその場所に設定していることを確認してから、もう一度試してください。
  • amountAboveLimit : <デバイス> の最大許容量を超えています。
  • appLaunchFailed : 申し訳ございませんが、<デバイス> で <アプリ名> を起動できませんでした。
  • armFailure : <デバイス> を監視できませんでした。
  • armLevelNeeded : <device(s)> をどのレベルに設定するかがわかりません。「<デバイス> を <低セキュリティ> に設定して」または「<デバイス> を <高セキュリティ> に設定して」と言ってみてください。
  • authFailure : <デバイス> にアクセスできません。アプリで <デバイス> の設定が完了していることを確認してください。
  • bagFull : <デバイス> のバッグが一杯です。空にしてからもう一度お試しください。
  • belowMinimumLightEffectsDuration : 設定できる最短時間は 5 分です。もう一度お試しください。
  • belowMinimumTimerDuration : <device(s)> の設定時間が短すぎます。もう一度お試しください。
  • binFull : <device(s)> <has/have> <a full bin/full bins>.
  • cancelArmingRestricted : 申し訳ありませんが、<デバイス> の警戒モードを解除できませんでした。
  • cancelTooLate : キャンセルが間に合いませんでした。代わりに <デバイス> またはアプリを使用してください。
  • channelSwitchFailed : <channel name> に切り替えられませんでした。後ほど試してください。
  • chargerIssue : すみません、<デバイス> の <充電器に問題が発生しています / 充電器に問題が発生しています>。
  • commandInsertFailed : <デバイス> のコマンドを処理できません。
  • deadBattery : <デバイス> の <バッテリーが切れています>。
  • degreesOutOfRange : リクエストされた数値は <デバイス> の設定範囲外です。
  • deviceAlertNeedsAssistance : <device(s)> <has/have> an active alert and <need(s)> your assistance.
  • deviceAtExtremeTemperature : <デバイス> が <極端な温度> になっています。
  • deviceBusy : 申し訳ございません。<デバイス> は現在作動中です。
  • deviceCharging : すみません、<device(s)> は充電中のため、その操作を行えません。
  • deviceClogged : <デバイス> が詰まっています。
  • deviceCurrentlyDispensing : <デバイス> は現在給餌中です。
  • deviceDoorOpen : <デバイス> のドアが開いています。ドアを閉じてからもう一度お試しください。
  • deviceHandleClosed : <デバイス> のハンドルが閉じられています。開いてからもう一度お試しください。
  • deviceJammingDetected : <device(s)> <is/are> jammed.
  • deviceLidOpen : <デバイス> の蓋が開いています。蓋を閉じてからもう一度お試しください。
  • deviceNeedsRepair : <デバイス> の修理が必要です。お近くの販売業者にお問い合わせください。
  • deviceNotDocked : 申し訳ありませんが、<デバイス> がドッキングされていないようです。<それ/それら> をドッキングしてから、もう一度お試しください。
  • deviceNotFound : <device(s)> <is/are>n't available. もう一度セットアップしてみてください。
  • deviceNotMounted : すみません、<デバイス> は取り付けられていないため、その操作を行えません。
  • deviceNotReady : <デバイス> の準備ができていません。
  • deviceStuck : <デバイス> が動かなくなっており、サポートが必要です。
  • deviceTampered : <device(s)> <has/have> been tampered with.
  • deviceThermalShutdown : 周辺温度が高すぎるか低すぎるため、<デバイス> は停止しました。
  • directResponseOnlyUnreachable : <デバイス> はリモコンに対応していません。
  • disarmFailure : <device(s)> を解除できませんでした。
  • discreteOnlyOpenClose : 申し訳ありませんが、<デバイス> は完全に開閉することしかできません。
  • dispenseAmountAboveLimit : <device(s)> の給餌量が多すぎます。
  • dispenseAmountBelowLimit : <device(s)> の給餌量が少なすぎます。
  • dispenseAmountRemainingExceeded : <デバイス> には、<ディスペンス アイテム> が不足しています。
  • dispenseFractionalAmountNotSupported : <デバイス> は <ディスペンス アイテム> の一部をディスペンスできません。
  • dispenseFractionalUnitNotSupported : <デバイス> は <ディスペンス アイテム> のその単位の端数をサポートしていません。
  • dispenseUnitNotSupported : <デバイス> は <ディスペンス アイテム> の単位をサポートしていません。
  • doorClosedTooLong : <デバイス> のドアが前回使用時から開けられていません。ドアを開けて中にものが入っていることを確認してから、もう一度試してください。
  • emergencyHeatOn : <device(s)> <is/are> in Emergency Heat Mode, so <it/they>'ll have to be adjusted by hand.
  • faultyBattery : <device(s)> <has/have> <a faulty battery/faulty batteries>.
  • floorUnreachable : <device(s)> がその部屋まで移動できません。<デバイス> を正しい階に移動してから、もう一度お試しください。
  • functionNotSupported : <デバイス> はその機能に対応していません。
  • genericDispenseNotSupported : 取り出すアイテムの名前を指定してもう一度試してください。
  • hardError : エラーが発生したためスマートホーム デバイスを操作できません。
  • hardError : エラーが発生したためスマートホーム デバイスを操作できません。
  • inAutoMode : <device(s)> <is/are> 現在自動モードに設定されています。温度を変更するには、別のモードに切り替えてください。
  • inAwayMode : <デバイス> は現在、外出モードに設定されています。サーモスタットを操作するには、スマートフォン、タブレット、またはパソコンの Nest アプリを使用して、手動で在宅モードに切り替えてください。
  • inDryMode : <デバイス> が現在ドライモードに設定されています。温度を変更するには、別のモードに切り替えてください。
  • inEcoMode : <デバイス> は現在エコモードに設定されています。温度を変更するには、別のモードに切り替えてください。
  • inFanOnlyMode : <device(s)> <is/are> 現在送風のみのモードに設定されています。温度を変更するには、別のモードに切り替えてください。
  • inHeatOrCool : <device(s)> <is/are>n't in heat/cool mode.
  • inHumidifierMode : <device(s)> <is/are> 現在加湿モードに設定されています。温度を変更するには、別のモードに切り替えてください。
  • inOffMode : <device(s)> <is/are> currently off. To change the temperature, you'll need to switch <it/them> to a different mode.
  • inPurifierMode : <device(s)> <is/are> currently set to purifier mode. 温度を変更するには、別のモードに切り替えてください。
  • inSleepMode : <デバイス> がスリープモードになっている。しばらくしてからもう一度お試しください。
  • inSoftwareUpdate : <device(s)> <is/are> currently in a software update.
  • lockFailure : <デバイス> をロックできませんでした。
  • lockedState : <デバイス> は現在ロックされています。
  • lockedToRange : その温度は <デバイス> の固定範囲外です。
  • lowBattery : <デバイス> のバッテリー残量が少なくなっています。
  • maxSettingReached : <device(s)> <is/are> already set to the highest setting.
  • maxSpeedReached : <デバイス> はすでに最大速度に設定されています。
  • minSettingReached : <デバイス> はすでに最小設定になっています。
  • minSpeedReached : <デバイス> はすでに最小速度に設定されています。
  • monitoringServiceConnectionLost : <device(s)> <has/have> lost <its/their> connection to the monitoring service.
  • needsAttachment : <device(s)> に必要なアタッチメントがありません。取り付けてから、もう一度試してください。
  • needsBin : <デバイス> にダストボックスがないようです。取り付けてから、もう一度試してください。
  • needsPads : <デバイス> は新しいパッドを必要としています。
  • needsSoftwareUpdate : <デバイス> はソフトウェア アップデートを必要としています。
  • needsWater : <デバイス> に水が必要です。
  • networkProfileNotRecognized : 申し訳ありませんが、<デバイス> の "<ネットワーク プロファイル>" を認識できません。
  • networkSpeedTestInProgress : <network> の <speed/speeds> をすでにテストしています。
  • noAvailableApp : 申し訳ございませんが、<アプリ名> はご利用いただけません。
  • noAvailableChannel : すみません、<チャンネル名> は利用できません。
  • noChannelSubscription : 申し訳ございませんが、現在 <チャンネル名> チャンネルに登録されていません。
  • noTimerExists : <デバイス> に設定されているタイマーはありません。
  • notSupported : 申し訳ございませんが、このモードは <デバイス> ではご利用いただけません。
  • obstructionDetected : <デバイス> が障害物を検出しました。
  • offline , deviceOffline : 申し訳ございません。現在、<デバイス> はご利用いただけません。
  • onRequiresMode : オンにするモードを指定してください。
  • passphraseIncorrect : PIN が正しくありません。
  • percentOutOfRange : 申し訳ありませんが、<デバイス> を <パーセント> に設定できません。
  • pinIncorrect : (passphraseIncorrect)
  • rainDetected : 雨が検知されたため、<デバイス> を開けませんでした。
  • rangeTooClose : 指定した温度は、<デバイス> の暖房・冷房モードの範囲に近すぎます。もっと差がある温度を指定してください。
  • relinkRequired : お使いのアカウントでエラーが発生しました。Google Home アプリまたはアシスタント アプリで <デバイス> をリンクし直してください。
  • remoteSetDisabled :
    • 省略可能なパラメータ errorCodeReason
    • currentlyArmed - すでにセキュリティシステムにより監視中です。変更は <デバイス> またはアプリから行ってください。
    • remoteUnlockNotAllowed - 申し訳ございませんが、<デバイス> のリモート ロック解除はできません。
    • remoteControlOff - その操作は無効になっています。<デバイス> のリモートコントロールを有効にしてから、もう一度試してください。
    • childSafetyModeActive - チャイルドセーフティモードが有効になっている場合、<デバイス> に対するその操作は無効になります。
  • roomsOnDifferentFloors : <デバイス> は別の階にあるため、これらの部屋に入ることができません。
  • safetyShutOff : <デバイス> は安全遮断モードになっているため、手動で調整してください。
  • sceneCannotBeApplied : 申し訳ありませんが、<デバイス> を適用できません。
  • securityRestriction : <デバイス> にセキュリティ制限があります。
  • softwareUpdateNotAvailable : 申し訳ございませんが、<デバイス> で利用可能なソフトウェア アップデートはありません。
  • startRequiresTime : その操作を行うには、<デバイス> の作動時間を指定してください。
  • stillCoolingDown : <デバイス> はまだ冷却中です。
  • stillWarmingUp : <device(s)> <is/are> still warming up.
  • streamUnavailable : <デバイス> からのストリームは現在利用できません。
  • streamUnplayable : 申し訳ありませんが、現時点では <デバイス> からのストリームを再生できません。
  • tankEmpty : <デバイス> の <タンク/タンク> が空になっています。<タンク/タンク> を補充して、もう一度お試しください。
  • targetAlreadyReached : すでにその温度に設定されています。
  • timerValueOutOfRange : <device(s)> をその時間に設定することはできません。
  • tooManyFailedAttempts : 失敗回数が多すぎます。デバイスのアプリでアクションを完了してください。
  • transientError : <デバイス> の操作でエラーが発生しました。もう一度お試しください。
  • turnedOff , deviceTurnedOff : <デバイス> は現在オフになっています。
  • unableToLocateDevice : <デバイス> を見つけることができませんでした。
  • unknownFoodPreset : <デバイス> は、そのプリセット メニューに対応していません。
  • unlockFailure : <デバイス> をロック解除できませんでした。
  • unpausableState : <デバイス> は現在一時停止できません。
  • userCancelled : ok
  • valueOutOfRange : <device(s)> をその温度に設定することはできません。

オンラインとオフラインの状態のレポート

デバイスがオフラインの場合は、デバイスの動作から 5 分以内に Report State に <code{"online": code="" dir="ltr" false}<="" translate="no"> を通知する必要があります。逆に、デバイスがオンライン状態に戻った場合は、デバイスの動作から 5 分以内に Report State に <code{"online": code="" dir="ltr" translate="no" true}<=""> を通知する必要があります。デバイスがオンラインに戻るたびに、パートナーは reportStateAndNotification API を使用して、現在のデバイスの状態をすべて報告する必要があります。この例は、light デバイスタイプがオンラインであり、現在のすべてのデバイスの状態をレポートしていることを示しています。
"requestId": "test-request-id",
  "agentUserId": "agent-user-1",
    "payload":{
      "devices": {
        "states": {
          "device-id-1": {
            "brightness": 65,
            "on": true,
            "online": true
          }
          "notifications": {},
        }
      }
    }

例外

コマンドに関連付けられた問題やアラートがある場合は、例外を返す必要があります。コマンドは成功することも失敗することもあります。

コマンドが成功した場合(ステータス = 「SUCCESS」)、StatusReport トレイト(ターゲット以外のデバイスの場合)を使用するか、適切な exceptionCode(ターゲット デバイスの場合)を返すことで、例外を報告します。

たとえば、乾燥機の糸くずフィルターがいっぱいになっても乾燥機を起動できますが、この状態についてユーザーに警告したい場合があります。同様に、デバイスのバッテリー残量が少ない場合でもコマンドを実行できますが、デバイスのバッテリー残量が少ないことをユーザーに知らせる必要があります。

例外によりコマンドが失敗した場合、ステータスは「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)

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

{
  "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 : <デバイス> のバッグが一杯です。空にしてからもう一度お試しください。
  • binFull : <device(s)> <has/have> <a full bin/full bins>.
  • carbonMonoxideDetected : <家名> で一酸化炭素が検出されました。
  • deviceAtExtremeTemperature : <デバイス> が <極端な温度> になっています。
  • deviceJammingDetected : <device(s)> <is/are> jammed.
  • deviceMoved : <device(s)> <was/were> moved.
  • deviceOpen : <デバイス> が開いています。
  • deviceTampered : <device(s)> <has/have> been tampered with.
  • deviceUnplugged : <デバイス> が取り外されました。
  • floorUnreachable : <device(s)> がその部屋まで移動できません。<デバイス> を正しい階に移動してから、もう一度お試しください。
  • hardwareFailure : <device(s)> <has/have> a hardware problem.
  • inSoftwareUpdate : <device(s)> <is/are> currently in a software update.
  • isBypassed : <デバイス> は現在バイパスされています。
  • lowBattery : <デバイス> のバッテリー残量が少なくなっています。
  • motionDetected : <デバイス> が <検出> モーションを検出しました。
  • needsPads : <デバイス> は新しいパッドを必要としています。
  • needsSoftwareUpdate : <デバイス> はソフトウェア アップデートを必要としています。
  • needsWater : <デバイス> に水が必要です。
  • networkJammingDetected : ホームネットワークと <デバイス> が接続されていません。
  • noIssuesReported : <デバイス> で問題は報告されていません。
  • roomsOnDifferentFloors : <デバイス> は別の階にあるため、これらの部屋に入ることができません。
  • runCycleFinished : <device(s)> <has/have> finished running.
  • securityRestriction : <デバイス> にセキュリティ制限があります。
  • smokeDetected : <家名> で煙が検出されました。
  • tankEmpty : <デバイス> の <タンク/タンク> が空になっています。<タンク/タンク> を補充して、もう一度お試しください。
  • usingCellularBackup : <device(s)> <is/are> using cellular backup.
  • waterLeakDetected : <device(s)> <detect(s)> a water leak.
</code{"online":></code{"online":>