Google は、サードパーティ製スマートホームアカウントのリンクを Google Home アプリ内で完全に独立して処理するように移行しています。2026 年 10 月 30 日までに統合の更新が必要になる場合があります。詳しくは、アカウントリンクの移行ガイドをご覧ください。

Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

エラーと例外

このドキュメントでは、スマートホームデバイスで公式にサポートされているエラーと例外について説明します。インテントレスポンスまたは通知（実装している場合）で、これらのエラーコードと例外コードを使用してください。これにより、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 : <デバイス> はすでに開いています。
alreadyPaused : <デバイス> はすでに一時停止されています。
alreadyStarted : <device(s)> <is/are> already started.
alreadyStopped : <デバイス> はすでに停止しています。
alreadyUnlocked : <デバイス> はすでにロック解除されています。
ambiguousZoneName : すみません。<デバイス> は、どのエリアを指しているのかを特定できません。ゾーンに一意の名前が付けられていることを確認してから、もう一度お試しください。
amountAboveLimit : <デバイス> の最大許容量を超えています。
appLaunchFailed : 申し訳ありません。<デバイス名> で <アプリ名> を起動できませんでした。 ヒント: appId と、アプリが対象のハードウェアでサポートされていることを確認してください。
armFailure : <デバイス> を監視モードにできませんでした。
armLevelNeeded : <デバイス> をどのレベルに設定するかがわかりません。「<デバイス> を <低セキュリティ> に設定して」、「<デバイス> を <高セキュリティ> に設定して」のように言ってみてください。
authFailure : <デバイス> にアクセスできないようです。<デバイス> の設定が完了していることをアプリで確認してみてください。
bagFull : <デバイス>のゴミが一杯です。空にしてからもう一度試してください。
belowMinimumLightEffectsDuration : 5 分未満です。もう一度お試しください。
belowMinimumTimerDuration : <デバイス> の設定時間が短すぎます。もう一度お試しください。
binFull : <デバイス> の <ダストボックスがいっぱいです>。
cancelArmingRestricted : すみません。<デバイス> の武装をキャンセルできませんでした。
cancelTooLate : 申し訳ございませんが、キャンセル可能な期間を過ぎています。代わりに <デバイス> またはアプリを使用してください。
channelSwitchFailed : すみません、<チャンネル名> に切り替えられませんでした。後ほど試してください。 ヒント: ユーザーのチャンネル名/番号と定期購入のステータスを確認します。
chargerIssue : すみません、<デバイス> の <充電器に問題が発生しています / 充電器に問題が発生しています>。 ヒント: パートナーは、ハードウェアレベルのテレメトリーとバッテリーヘルスを調査する必要があります。
commandInsertFailed : <デバイス> のコマンドを処理できません。 ヒント: データベースの書き込みパフォーマンスまたは内部コマンドのキューイングロジックを調査してください。
deadBattery : <デバイス> のバッテリーが切れています。
degreesOutOfRange : リクエストされた数値は <デバイス> の設定範囲外です。
deviceAlertNeedsAssistance : <デバイス> にアクティブなアラートがあり、対応が必要です。
deviceAtExtremeTemperature : <デバイス> が<極端な温度>になっています。
deviceBusy : すみません。<デバイス> は現在作動中です。
deviceCharging : すみません、<デバイス>は充電中のため、その操作を行えません。
deviceClogged : <デバイス> が詰まっています。
deviceCurrentlyDispensing : <デバイス> は現在給餌中です。
deviceDoorOpen : <デバイス> のドアが開いています。ドアを閉めてからもう一度お試しください。
deviceHandleClosed : <デバイス> のハンドルが閉じています。開いてからもう一度お試しください。
deviceJammingDetected : <デバイス> が妨害されています。
deviceLidOpen : <デバイス> のカバーが開いています。カバーを閉じてから、もう一度お試しください。
deviceNeedsRepair : <デバイス> の修理が必要です。お近くのサービスディーラーにお問い合わせください。
deviceNotDocked : すみません。<デバイス> がドッキングされていないようです。<it/them> をドッキングしてからもう一度試してください。
deviceNotFound : <デバイス> は利用できません。もう一度セットアップしてみてください。ヒント: バックエンドが常に Home Graph を同期するようにしてください。デバイスが追加または削除されるたびに requestSync を呼び出します。
deviceNotMounted : すみません、<デバイス> は取り付けられていないため、その操作を行えません。
deviceNotReady : <デバイス> の準備ができていません。
deviceStuck : <デバイス> が動けなくなっています。対応が必要です。
deviceTampered : <デバイス> が改ざんされています。
deviceThermalShutdown : すみません、周辺温度が高すぎるか低すぎるため、<デバイス> は停止しました。
directResponseOnlyUnreachable : <デバイス> はリモコンに対応していません。
disarmFailure : <デバイス> の解除に失敗しました。
discreteOnlyOpenClose : すみません。<デバイス> は全開または全閉のみ可能です。
dispenseAmountAboveLimit : <デバイス> の給餌量が多すぎます。
dispenseAmountBelowLimit : <デバイス> の給餌量が少なすぎます。
dispenseAmountRemainingExceeded : <デバイス> には、その操作を行うのに十分な <給餌アイテム> がありません。
dispenseFractionalAmountNotSupported : <デバイス> は <ディスペンスアイテム> の端数をディスペンスできません。
dispenseFractionalUnitNotSupported : <デバイス> の <dispense item> の量に対するその単位に小数点は使用できません。
dispenseUnitNotSupported : <デバイス> は <ディスペンスアイテム> のその単位をサポートしていません。
doorClosedTooLong : <デバイス> のドアが前回使用時から開けられていません。ドアを開けて中にものが入っていることを確認してから、もう一度試してください。
emergencyHeatOn : <デバイス> は緊急ヒーターモードになっているため、手動で調整する必要があります。
faultyBattery : <デバイス> のバッテリーに不具合があります。
floorUnreachable : <デバイス> がその部屋まで移動できません。<it/them>を部屋のある階に運んでからもう一度試してください。
functionNotSupported : 実際には、<デバイス> はその機能に対応していません。 ヒント: SYNC レスポンスがデバイスの機能を正確に反映していることを確認してください。
genericDispenseNotSupported : 何をディスペンスしたいか教えてください。アイテムの名前を指定してもう一度お試しください。
hardError : エラーが発生したためスマートホームデバイスを操作できません。
hardError : エラーが発生したためスマートホームデバイスを操作できません。
inAutoMode : <デバイス> は現在、自動モードに設定されています。温度を変更するには、<it/them> を別のモードに切り替える必要があります。
inAwayMode : <デバイス> は現在、外出モードに設定されています。サーモスタットを操作するには、スマートフォン、タブレット、パソコンの Nest アプリを使用して、手動で在宅モードに切り替える必要があります。
inDryMode : <デバイス> は現在、ドライモードに設定されています。温度を変更するには、<it/them> を別のモードに切り替える必要があります。
inEcoMode : <デバイス> は現在、エコモードに設定されています。温度を変更するには、<it/them> を別のモードに切り替える必要があります。
inFanOnlyMode : <デバイス> は現在、ファンのみのモードに設定されています。温度を変更するには、<it/them> を別のモードに切り替える必要があります。
inHeatOrCool : <デバイス> は暖房 / 冷房モードではありません。
inHumidifierMode : <デバイス> は現在、加湿器モードに設定されています。温度を変更するには、<it/them> を別のモードに切り替える必要があります。
inOffMode : <デバイス> は現在オフになっています。温度を変更するには、別のモードに切り替える必要があります。
inPurifierMode : <デバイス> は現在、空気清浄機モードに設定されています。温度を変更するには、<it/them> を別のモードに切り替える必要があります。
inSleepMode : <デバイス> はおやすみモードです。しばらくしてからもう一度お試しください。
inSoftwareUpdate : <デバイス> は現在ソフトウェアアップデート中です。
lockFailure : <デバイス> をロックできませんでした。 ヒント: ロックのハードウェアに物理的な詰まり、電力不足、モーターの故障がないか確認します。
lockedState : <デバイス> は現在ロックされています。
lockedToRange : その温度は <デバイス> のロックされた範囲外です。
lowBattery : <デバイス> のバッテリー残量が少なくなっています。
maxSettingReached : <デバイス> はすでに最高の設定になっています。
maxSpeedReached : <デバイス> はすでに最大速度に設定されています。
minSettingReached : <デバイス> はすでに最低の設定になっています。
minSpeedReached : <デバイス> はすでに最低速度に設定されています。
monitoringServiceConnectionLost : <デバイス> とモニタリングサービスの接続が切断されました。
needsAttachment : すみません。<デバイス> に必要なアタッチメントがありません。取り付けてから、もう一度試してください。
needsBin : すみません。<デバイス> にダストボックスがないようです。取り付けてから、もう一度試してください。
needsPads : <デバイス> には新しいパッドが <必要> です。
needsSoftwareUpdate : <device(s)> <need(s)> a software update.
needsWater : <デバイス>は水が必要です。
networkProfileNotRecognized : すみません。<デバイス> の「<ネットワークプロファイル>」を認識できません。 ヒント: プロファイル名の文字列が、SYNC レスポンスでサポートされているプロファイルと一致していることを確認してください。
networkSpeedTestInProgress : <ネットワーク> の <速度> をテスト中です。
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 : <デバイス> はまだウォームアップ中です。
streamUnavailable : すみません。現在、<デバイス> からのストリーミングは利用できないようです。
streamUnplayable : すみません、現在 <デバイス> からのストリーミングを再生できません。 ヒント: WebRTC/HLS シグナリングを確認し、ストリーム URL が有効であることを確認します。
tankEmpty : <デバイス> のタンクが空です。タンクに補充してから、もう一度お試しください。
targetAlreadyReached : すみません。すでに現在の温度になっているようです。
timerValueOutOfRange : <デバイス> はその時間には設定できません。
tooManyFailedAttempts : 申し訳ありません。試行回数が上限に達しました。デバイスのアプリでそのアクションを完了してください。
transientError : <デバイス> の操作でエラーが発生しました。もう一度お試しください。 ヒント: 通常、これらのエラーはデバイスまたはサービスへの接続が切断されたときに発生します。また、サーバーへの新しい接続を開けない場合も同様です。
turnedOff , deviceTurnedOff : <デバイス> は現在オフになっています。
unableToLocateDevice : <デバイス> を見つけることができませんでした。 ヒント: デバイスのローカル接続（Wi-Fi/Bluetooth）を確認してください。
unknownFoodPreset : <デバイス> は、そのプリセットメニューに対応していません。
unlockFailure : <デバイス> のロックを解除できませんでした。 ヒント: ハードウェアの詰まり、バッテリー残量の低下、無効な PIN の入力がないか確認します。
unpausableState : 現在、<デバイス> を一時停止できません。
userCancelled : ok
valueOutOfRange : <デバイス> をその温度に設定できません。

オンラインとオフラインの状態の報告

デバイスがオフラインの場合は、デバイスの動作から 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 : <デバイス> の <ダストボックスがいっぱいです>。
carbonMonoxideDetected : <家の名前> で一酸化炭素が検出されました。
deviceAtExtremeTemperature : <device(s)> <is/are> at <an extreme temperature/extreme temperatures>.
deviceJammingDetected : <デバイス> が妨害されています。
deviceMoved : <デバイス> を移動しました。
deviceOpen : <デバイス> が開いています。
deviceTampered : <デバイス> が改ざんされています。
deviceUnplugged : <デバイス> が接続されていません。
floorUnreachable : <デバイス> がその部屋まで移動できません。<it/them>を部屋のある階に運んでからもう一度試してください。
hardwareFailure : <デバイス> にハードウェアの問題があります。
inSoftwareUpdate : <デバイス> は現在ソフトウェアアップデート中です。
isBypassed : <デバイス> は現在バイパスされています。
lowBattery : <デバイス> のバッテリー残量が少なくなっています。
motionDetected : <デバイス> が動きを検知しました。
needsPads : <デバイス> には新しいパッドが <必要> です。
needsSoftwareUpdate : <device(s)> <need(s)> a software update.
needsWater : <デバイス>は水が必要です。
networkJammingDetected : <デバイス> へのホームネットワーク接続が正常に機能していません。
noIssuesReported : <デバイス> で問題は報告されていません。
roomsOnDifferentFloors : <デバイス> は別の階にあるため、その部屋まで移動できません。
runCycleFinished : <デバイス> の実行が完了しました。
securityRestriction : <デバイス> にはセキュリティ制限があります。
smokeDetected : <家の名前> で煙が検知されました。
tankEmpty : <デバイス> のタンクが空です。タンクに補充してから、もう一度お試しください。
usingCellularBackup : <デバイス> は遠隔バックアップを使用しています。
waterLeakDetected : <デバイス> が水漏れを検知しました。

</code{"online":></code{"online":>