スマートホームアクションの開発方法を学ぶための新しいデベロッパーセンター、Google Home Developer Center へようこそ。

このページは Cloud Translation API によって翻訳されました。

エラーと例外
コレクションでコンテンツを整理必要に応じて、コンテンツの保存と分類を行います。

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

エラー

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

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

デバイスがオフラインの場合は、デバイスの動作から 5 分以内に Report State に {"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 時間です。もう一度お試しください。
aboveMaximumTimerDuration : <デバイス> を <時間> までしか設定できません
actionNotAvailable : 申し訳ございませんが、現在その操作は行えません。
actionUnavailableWhileRunning : <デバイス> は現在実行中であるため、変更できません。
alreadyArmed : <デバイス> はすでに監視中です。
alreadyAtMax : <デバイス> はすでに最大温度に設定されています。
alreadyAtMin : <デバイス> はすでに最低温度に設定されています。
alreadyClosed : <device(s)> はすでに閉じられています。
alreadyDisarmed : <デバイス> はすでに解除されています。
alreadyDocked : <デバイス> はすでにホルダーにセットされています。
alreadyInState : <device(s)> はすでにその状態です。
alreadyLocked : <デバイス> はすでにロックされています。
alreadyOff : <デバイス> はすでにオフになっています。
alreadyOn : <デバイス> はすでにオンになっています。
alreadyOpen : <device(s)> はすでに開いています。
alreadyPaused : <デバイス> はすでに一時停止されています。
alreadyStarted : <device(s)> はすでに開始されています。
alreadyStopped : <device(s)> はすでに停止されています。
alreadyUnlocked : <デバイス> はすでにロック解除されています。
ambiguousZoneName : 申し訳ございませんが、<デバイス> では、どのゾーンを指しているか特定できません。固有の名前をその場所に設定していることを確認してから、もう一度試してください。
amountAboveLimit : <デバイス> の最大許容量を超えています。
appLaunchFailed : 申し訳ございません。<デバイス> で <アプリ名> を起動できませんでした。
armFailure : <デバイス>を監視できませんでした。
armLevelNeeded : <デバイス> をどのレベルに設定するかがわかりません。「<デバイス> を <低いセキュリティ> に設定」または「<デバイス> を <高いセキュリティ> に設定」と言ってみてください
authFailure : <デバイス> にアクセスできません。アプリで、<デバイス> が完全に設定されていることを確認してください。
bagFull : <デバイス> の <バッグ> が <一杯>です。空にしてからもう一度お試しください。
belowMinimumLightEffectsDuration : 最短設定時間は 5 分です。もう一度お試しください。
belowMinimumTimerDuration : <デバイス> の設定時間が短すぎます。もう一度お試しください。
binFull : <device(s)> <has/have> <a full bin/full bins>.
cancelArmingRestricted : 申し訳ございません。<デバイス> の起動をキャンセルできませんでした。
cancelTooLate : 申し訳ございませんが、キャンセルの期限を過ぎています。代わりに <device(s)> またはアプリを使用してください。
channelSwitchFailed : チャンネル <channel name> に切り替えられませんでした。後ほどもう一度お試しください。
充電器に関する問題 : <デバイス> の充電器に問題があるようです。
commandInsertFailed : <device(s)> のコマンドを処理できません。
deadBattery : <デバイス> に <電池切れ> があります。
degreesOutOfRange : リクエストされた角度は <デバイス> の範囲外です。
deviceAlertNeedsAssistance : <デバイス> でアクティブなアラートが <発生> しており、<サポート> が必要です。
deviceAtExtremeTemperature : <デバイス> の温度が <極端に高温/極端に低温> です。
deviceBusy : <デバイス> は現在何か処理を行っているようですので、ご利用いただけません。
deviceCharging : すみません、<device(s)> は充電中のため、その操作を行えません（ha_shared.ItsTheyre size=$item.devices.total_device_count）。
deviceClogged : <デバイス> が詰まっているようです。
deviceCurrentlyDispensing : <デバイス> は現在給餌中です。
deviceDoorOpen : <デバイス> のドアが開いています。閉じてからもう一度お試しください。
deviceHandleClosed : <デバイス> でハンドルが閉じています。開いてからもう一度お試しください。
deviceJammingDetected : <device(s)> <is/are> jammed.
deviceLidOpen : <デバイス> の蓋が開いています。閉じてからもう一度お試しください。
deviceNeedsRepair : <device(s)> <need(s)> to be repaired. 近くの販売業者にお問い合わせください。
deviceNotDocked : 申し訳ございませんが、<デバイス> がホルダーにセットされていないようです。ドッキングしてからもう一度お試しください。
deviceNotFound : <device(s)> <is/are>n't available. もう一度セットアップしてみてください。
deviceNotMounted : すみません、<デバイス> は取り付けられていないため、その操作を行えません。
deviceNotReady : <デバイス> が準備ができていません。
deviceStuck : <デバイス> が停止しているため、サポートが必要です。
deviceTampered : <device(s)> <has/have> been tampered with.
deviceThermalShutdown : 周辺温度が高すぎるか低すぎるため、<デバイス> は停止しました。
directResponseOnlyUnreachable : <device(s)> <doesn't/don't> support remote control.
disarmFailure : <device(s)> を解除できませんでした。
discreteOnlyOpenClose : 申し訳ございませんが、<デバイス> は完全に開閉することしかできません。
dispenseAmountAboveLimit : <デバイス> の給餌量が多すぎます。
dispenseAmountBelowLimit : <device(s)> の給餌量が少なすぎます。
dispenseAmountRemainingExceeded : <device(s)> に、その操作を行うのに十分な <dispense item> がありません。
dispenseFractionalAmountNotSupported : <device(s)> は <dispense item> の少数部分を分注できません。
dispenseFractionalUnitNotSupported : <デバイス> は、<dispense item> のその単位の小数点以下をサポートしていません。
dispenseUnitNotSupported : <device(s)> は <dispense item> の単位をサポートしていません。
doorClosedTooLong : <デバイス> のドアが前回使用時から開けられていません。ドアを開けて中にものが入っていることを確認してから、もう一度試してください。
emergencyHeatOn : <デバイス> は緊急ヒーターモードになっているため、手動で調整する必要があります。
faultyBattery : <device(s)> <has/have> <a faulty battery/faulty batteries>.
floorUnreachable : <device(s)> がその部屋まで移動できません。部屋のある階に移動してからもう一度お試しください。
functionNotSupported : <デバイス> は、その機能をサポートしていません。
genericDispenseNotSupported : 取り出すアイテムの名前を教えていただけますか？商品名を入力してもう一度お試しください。
hardError : エラーが発生したため、スマートホームデバイスを操作できません。
hardError : エラーが発生したため、スマートホームデバイスを操作できません。
inAutoMode : <device(s)> <is/are> currently set to auto mode. 温度を変更するには、別のモードに切り替えてください。
inAwayMode : <device(s)> は現在外出モードに設定されています。サーモスタットを操作するには、スマートフォン、タブレット、またはパソコンの Nest アプリを使用して、手動で在宅モードに切り替えてください。
inDryMode : <device(s)> は現在ドライモードに設定されています。温度を変更するには、別のモードに切り替えてください。
inEcoMode : <デバイス> は現在エコモードに設定されています。温度を変更するには、別のモードに切り替えてください。
inFanOnlyMode : <デバイス> は現在、送風のみのモードに設定されています。温度を変更するには、別のモードに切り替えてください。
inHeatOrCool : <デバイス> が暖房 / 冷房モードではありません。
inHumidifierMode : <device(s)> <is/are> currently set to humidifier mode. 温度を変更するには、別のモードに切り替えてください。
inOffMode : <デバイス> は現在オフになっています。温度を変更するには、<デバイス> を別のモードに切り替える必要があります。
inPurifierMode : <device(s)> は現在、空気清浄機モードに設定されています。温度を変更するには、別のモードに切り替えてください。
inSleepMode : <device(s)> はスリープモードです。しばらくしてからもう一度お試しください。
inSoftwareUpdate : <デバイス> は現在ソフトウェアアップデート中です。
lockFailure : <device(s)> をロックできませんでした。
lockedState : <device(s)> <is/are> currently locked.
lockedToRange : その温度は <デバイス> の固定範囲外です。
lowBattery : <device(s)> のバッテリー残量が少ない。
maxSettingReached : <device(s)> はすでに最大設定に設定されています。
maxSpeedReached : <デバイス> はすでに最大速度に設定されています。
minSettingReached : <デバイス> はすでに最小設定に設定されています。
minSpeedReached : <デバイス> はすでに最小速度に設定されています。
monitoringServiceConnectionLost : <device> がモニタリングサービスとの接続を失いました。
needsAttachment : 申し訳ございませんが、<device(s)> に必要なアタッチメントがありません。取り付けてから、もう一度お試しください。
needsBin : <device(s)> にダストボックスがないようです。取り付けてから、もう一度お試しください。
needsPads : <device(s)> <need(s)> new pads.
needsSoftwareUpdate : <デバイス> はソフトウェアアップデートを <必要> としています。
needsWater : <device(s)> <need(s)> water.
networkProfileNotRecognized : 申し訳ございませんが、<デバイス> の <ネットワークプロファイル> は認識されませんでした。
networkSpeedTestInProgress : <ネットワーク> <速度/速度>> のテストはすでに行っています。
noAvailableApp : 申し訳ございませんが、<アプリ名> はご利用いただけないようです。
noAvailableChannel : チャンネル <チャンネル名> はご利用いただけません。
noChannelSubscription : 申し訳ございませんが、現在、チャンネル <channel name> に登録されていません。
noTimerExists : <デバイス> に設定されているタイマーはありません。
notSupported : 申し訳ございませんが、<デバイス> ではそのモードをご利用いただけません。
obstructionDetected : <デバイス> が障害物を検出しました。
offline , deviceOffline : 現在、<デバイス> はご利用いただけません。
onRequiresMode : オンにするモードを指定してください。
passphraseIncorrect : PIN が正しくありません。
percentOutOfRange : 申し訳ございませんが、<デバイス> を <%> に設定することはできません。
pinIncorrect : （passphraseIncorrect）
rainDetected : 雨が検知されたため、<デバイス> を開けませんでした。
rangeTooClose : 指定した温度は、<デバイス> の暖房・冷房モードの範囲に近すぎます。もっと差がある温度を指定してください。
relinkRequired : お使いのアカウントでエラーが発生しました。Google Home アプリまたはアシスタントアプリで <デバイス> をリンクし直してください。
remoteSetDisabled :
- 省略可能なパラメータ errorCodeReason
- currentlyArmed - すでにセキュリティシステムにより監視中です。変更は <device(s)> またはアプリから行ってください。
- remoteUnlockNotAllowed - 申し訳ございませんが、<デバイス> をリモートでロック解除することはできません。
- remoteControlOff - その操作は現在無効になっています。<デバイス> でリモートコントロールを有効にして、もう一度お試しください。
- childSafetyModeActive - チャイルドセーフティモードが有効になっている場合、<デバイス> に対するその操作は無効になります。
roomsOnDifferentFloors : <デバイス> は別の階にあるため、これらの部屋まで移動できません。
safetyShutOff : <デバイス> は安全遮断モードになっているため、手動で調整する必要があります。
sceneCannotBeApplied : 申し訳ございませんが、<デバイス> には適用できません。
securityRestriction : <デバイス> にセキュリティ制限があります。
softwareUpdateNotAvailable : 申し訳ございませんが、<デバイス> では利用可能なソフトウェアアップデートはありません。
startRequiresTime : その操作を行うには、<device(s)> の作動時間を指定してください。
stillCoolingDown : <デバイス> はまだ冷却中です。
stillWarmingUp : <デバイス> はまだ温まっていない。
streamUnavailable : 申し訳ございませんが、<デバイス> からのストリームは現在利用できません。
streamUnplayable : 申し訳ございませんが、<デバイス> からのストリームを現在再生できません。
tankEmpty : <デバイス> の <タンク> が <空> です。<タンク> に水を入れてから、もう一度お試しください。
targetAlreadyReached : すでにその温度に設定されています。
timerValueOutOfRange : <デバイス> をその時間に設定することはできません。
tooManyFailedAttempts : 失敗回数が多すぎます。デバイスのアプリでアクションを完了してください。
transientError : <device(s)> の操作でエラーが発生しました。もう一度お試しください。
turnedOff、deviceTurnedOff : 現在、<device> がオフになっています。
unableToLocateDevice : <デバイス> が見つかりませんでした。
unknownFoodPreset : <デバイス> は、そのフードプリセットに対応していません。
unlockFailure : <デバイス> をロック解除できませんでした。
unpausableState : <デバイス> は現在一時停止できません。
userCancelled : ok
valueOutOfRange : <デバイス> をその温度に設定することはできません。

例外

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

コマンドが成功した場合（ステータス =「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 : <device(s)> が開いています。
deviceTampered : <device(s)> <has/have> been tampered with.
deviceUnplugged : <device(s)> <is/are> unplugged.
floorUnreachable : <device(s)> がその部屋まで移動できません。部屋のある階に移動してからもう一度お試しください。
hardwareFailure : <device(s)> にハードウェアの問題がある。
inSoftwareUpdate : <デバイス> は現在ソフトウェアアップデート中です。
isBypassed : <device(s)> は現在バイパスされています。
lowBattery : <device(s)> のバッテリー残量が少ない。
motionDetected : <device(s)> <detect(s)> motion.
needsPads : <device(s)> <need(s)> new pads.
needsSoftwareUpdate : <デバイス> はソフトウェアアップデートを <必要> としています。
needsWater : <device(s)> <need(s)> water.
networkJammingDetected : <デバイス> へのホームネットワーク接続が正常に機能していません。
noIssuesReported : <デバイス> で問題は報告されていません。
roomsOnDifferentFloors : <デバイス> は別の階にあるため、これらの部屋まで移動できません。
runCycleFinished : <device(s)> は実行を終了しました。
securityRestriction : <デバイス> にセキュリティ制限があります。
smokeDetected : <家の名前> で煙が検出されました。
tankEmpty : <デバイス> の <タンク> が <空> です。<タンク> に水を入れてから、もう一度お試しください。
usingCellularBackup : <device(s)> はモバイルバックアップを使用しています。
waterLeakDetected : <device(s)> <detect(s)> 水漏れ。