Google 將全面改用 Google Home 應用程式，獨立處理第三方智慧住宅帳戶連結作業。請在 2026 年 10 月 30 日前更新整合服務。詳情請參閱帳戶連結遷移指南。

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

錯誤和例外狀況

本文列出智慧住宅裝置官方支援的錯誤和例外狀況。請在意圖回應或通知 (如有導入) 中使用這些錯誤和例外狀況代碼，讓 Google 助理在發生與特定指令或裝置狀態相關的問題時，提醒使用者。如果回應格式不正確或包含 errorCode，Google 助理會向使用者顯示一般錯誤訊息，例如「抱歉，<裝置>目前無法使用」。

錯誤

如果問題導致執行或查詢要求失敗，請傳回錯誤代碼。舉例來說，如果門鎖卡住，無法上鎖或解鎖，系統應向使用者傳回有關此狀態的錯誤。

錯誤代碼可以附加在裝置層級或全域層級。舉例來說，如果使用者有多個來自同一供應商的燈具，並由中樞控制，當使用者要求關閉所有燈具時，如果單一燈具離線，供應商可能會傳回裝置層級錯誤；如果整個中樞離線且無法控制任何燈具，則會傳回全域層級錯誤。如果所有裝置都離線，則使用全域層級或裝置層級錯誤並無差異。

摘要說明：

全域層級錯誤：回應中的所有裝置都有相同錯誤
區域層級錯誤：混合回應，包含錯誤和成功案例

全域層級錯誤

下列 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 ： <裝置>已啟動。
alreadyStopped ： <裝置>已停止。
alreadyUnlocked : <裝置>已解鎖。
ambiguousZoneName : 抱歉，<裝置>無法判斷你指的是哪個區域。請確認各區域的名稱不重複，然後再試一次。
amountAboveLimit : 這樣會超出<裝置>所能負荷的數量
appLaunchFailed ： 抱歉，無法在 <裝置>上啟動 <應用程式名稱>。 提示：請確認 appId 正確無誤，且目標硬體支援該應用程式。
armFailure ： 無法啟動<裝置>。
armLevelNeeded : 我不確定要將 <裝置> 設定在哪個層級。請試著說出「將 <裝置> 設為 <低安全性>」或「將 <裝置> 設為 <高安全性>」
authFailure ： 我似乎無法連上<裝置>。請前往應用程式確認<裝置>是否已設定完畢。
bagFull : <裝置>的<袋子滿了/多個袋子滿了>，請清空<袋子/多個袋子>後再試一次。
belowMinimumLightEffectsDuration : 這低於 5 分鐘的最低時間長度。請再試一次。
belowMinimumTimerDuration : 我無法為<裝置>設定這麼短的時間，請再試一次。
binFull ： <device(s)> <has/have> <a full bin/full bins>。
cancelArmingRestricted : 抱歉，我無法取消啟動<裝置>。
cancelTooLate : 抱歉，取消期限已過。請改用 <裝置> 或應用程式。
channelSwitchFailed : 抱歉，無法轉台到「<頻道名稱>」頻道，請稍後再試。 提示：請確認使用者的頻道名稱/號碼和訂閱狀態。
chargerIssue : 抱歉，<裝置>的充電器似乎有問題。 提示：合作夥伴應調查硬體層級的遙測資料和電池健康度。
commandInsertFailed ： 無法處理 <裝置> 的指令。 提示：請調查資料庫寫入效能或內部指令佇列邏輯。
deadBattery ： <裝置>沒電了。
degreesOutOfRange ： 指定的角度超出 <裝置> 可活動的範圍。
deviceAlertNeedsAssistance ： <裝置>有未處理的警示，需要你協助。
deviceAtExtremeTemperature ： <裝置>處於<極端溫度>。
deviceBusy : 抱歉，<裝置>正在執行其他動作。
deviceCharging : 抱歉，<device(s)>正在充電，因此無法執行這項動作。
deviceClogged : 抱歉，<裝置>似乎卡住了。
deviceCurrentlyDispensing ： <裝置>正在供應東西。
deviceDoorOpen : <裝置>的門已開啟，請關上並重試。
deviceHandleClosed : <裝置>的把手已關閉，請打開後再試一次。
deviceJammingDetected ： <裝置>遭到干擾。
deviceLidOpen : <裝置>的蓋子已打開，請關上後再試一次。
deviceNeedsRepair : <裝置>需要維修。請與當地服務經銷商聯絡。
deviceNotDocked : 抱歉，<裝置>似乎不在充電座上。請先將 <it/裝置>放回充電座，然後再試一次。
deviceNotFound ： <device(s)> <is/are>n't available. 建議你重新設定。提示：請確保後端一律與 Home Graph 保持同步。每當新增或移除裝置時，請呼叫 requestSync。
deviceNotMounted : 抱歉，<裝置>尚未安裝完畢，因此無法執行這個動作。
deviceNotReady ： <裝置>尚未就緒。
deviceStuck ： <裝置>卡住了，需要你協助。
deviceTampered ： <裝置>遭到竄改。
deviceThermalShutdown : 抱歉，<裝置>周遭環境的溫度過高/過低，因此已關閉
directResponseOnlyUnreachable : <裝置>不支援遠端控制。
disarmFailure ： 無法解除<裝置>的警報。
discreteOnlyOpenClose : 抱歉，<裝置>只能完全開啟或關閉。
dispenseAmountAboveLimit ： <裝置>無法供應這麼多的量。
dispenseAmountBelowLimit ： <裝置>無法供應這麼少的量。
dispenseAmountRemainingExceeded ： <裝置>沒有足夠的<給料項目>可執行這項操作。
dispenseFractionalAmountNotSupported ： <裝置>無法提供非整數的<提供項目>。
dispenseFractionalUnitNotSupported ： <裝置>無法以該單位供應非整數的<供應項目>。
dispenseUnitNotSupported ： <裝置>不支援<給皂機項目>的單位。
doorClosedTooLong : <裝置>的門關著一段時間了。請打開門確定一下裡面有放東西，然後再試一次。
emergencyHeatOn : <device(s)>目前處於緊急熱源模式，因此必須手動調整。
faultyBattery ： <裝置>的電池故障。
floorUnreachable ： <裝置>無法到達那個房間。請將 <裝置/這些裝置>移到正確的樓層，然後再試一次。
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 ： <裝置>需要軟體更新。
needsWater ： <裝置>需要水。
networkProfileNotRecognized ： 抱歉，我無法辨識 <裝置> 上的「<網路設定檔>」。 提示：請確認設定檔名稱字串與 SYNC 回應中支援的設定檔相符。
networkSpeedTestInProgress : 我正在測試<network><speed/speeds>>。
noAvailableApp ： 抱歉，<應用程式名稱> 似乎無法使用。
noAvailableChannel : 抱歉，沒有「<頻道名稱>」這個頻道
noChannelSubscription : 抱歉，你目前並未訂閱「<頻道名稱>」頻道。
noTimerExists : 抱歉，目前 <裝置> 沒有設定任何計時器。
notSupported ： 抱歉，<裝置>不支援該模式。
obstructionDetected ： <裝置>偵測到障礙物。
offline , deviceOffline : 抱歉，<裝置>目前似乎無法使用。
onRequiresMode ： 請指定要開啟的模式。
passphraseIncorrect : 抱歉，PIN 碼似乎不正確。
percentOutOfRange : 抱歉，我無法將<裝置>設為 <百分比>。
pinIncorrect ： (passphraseIncorrect)
rainDetected ： 因為偵測到雨水，所以我沒有開啟<裝置>。
rangeTooClose ： <device(s)> 的冷暖模式溫度範圍太接近，請選擇差距較大的溫度。
relinkRequired : 抱歉，帳戶出現錯誤。請透過 Google Home 或 Google 助理應用程式重新連結 <裝置>。 提示：請確認伺服器會在更新權杖永久失效時傳回這個代碼。
remoteSetDisabled :
- 選用參數 errorCodeReason
- currentlyArmed - 抱歉，保全系統已啟動，你必須透過 <裝置>或應用程式才能變更設定
- remoteUnlockNotAllowed - 抱歉，我無法從遠端解鎖<裝置>。
- remoteControlOff - 這個動作目前已停用。請啟用 <裝置>的遙控功能，然後再試一次。
- childSafetyModeActive - 如果兒童安全模式已啟用，就無法對 <裝置>執行這個動作
roomsOnDifferentFloors : <裝置>無法移動到那些房間，因為那些房間位於其他樓層。
safetyShutOff ： <裝置>處於安全關閉模式，因此必須手動調整。
sceneCannotBeApplied : 抱歉，無法套用<裝置>。 提示：請檢查使用者在合作夥伴雲端上的場景內部健康狀態。
securityRestriction ： <裝置>有安全限制。
softwareUpdateNotAvailable : 抱歉，<裝置>沒有可用的軟體更新。
startRequiresTime : 你必須先告訴我<裝置>要運轉多久，才能執行這個動作
stillCoolingDown ： <裝置>仍在降溫。
stillWarmingUp ： <裝置>仍在預熱。
streamUnavailable : 抱歉，<裝置> 目前似乎無法提供串流。
streamUnplayable : 抱歉，我目前無法播放 <裝置> 的串流影像。 提示：驗證 WebRTC/HLS 信號，並確認串流網址有效。
tankEmpty : <裝置>的水箱已空，請加水後再試一次。
targetAlreadyReached : 抱歉，這似乎已經是目前的溫度。
timerValueOutOfRange : 無法將 <裝置> 設定為該時間長度。
tooManyFailedAttempts : 抱歉，失敗次數過多。請前往裝置的應用程式完成這項操作。
transientError : 抱歉，控制 <裝置> 時發生錯誤，請再試一次。 提示：這類錯誤最常見的表現形式是與裝置或服務的連線中斷。如果無法開啟與伺服器的新連線，也會發生這種情況。
turnedOff , deviceTurnedOff ： <裝置>目前已關閉。
unableToLocateDevice ： 我找不到<裝置>。 提示：請檢查裝置的本機連線 (Wi-Fi/藍牙)。
unknownFoodPreset ： <裝置>不支援這項烹調預設設定。
unlockFailure ： 無法解鎖 <裝置>。 提示：請檢查硬體是否卡住、電池電量是否不足，或輸入的 PIN 碼是否無效。
unpausableState ： 目前無法暫停<裝置>。
userCancelled : ok
valueOutOfRange ： 無法將 <裝置> 設為該溫度。

線上和離線狀態回報

裝置離線時，請在裝置行為發生後五分鐘內，向回報狀態回報 <code{"online": code="" dir="ltr" false}<="" translate="no">。相反地，當裝置恢復連線狀態時，您應在裝置行為發生後的五分鐘內，向回報狀態回報 <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 特徵回報例外狀況。

目標裝置的非封鎖例外狀況 (成功)

以下是鎖門的範例：

前門智慧門鎖電量不足，正在鎖上前門。

{
  "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 的非封鎖例外狀況 (成功)

以下是啟動保全系統的範例：好的，正在啟動保全系統。前窗開著。

{
  "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 ： <裝置>遭到干擾。
deviceMoved ： <裝置>已移動。
deviceOpen ： <裝置>已開啟。
deviceTampered ： <裝置>遭到竄改。
deviceUnplugged ： <裝置>已拔除。
floorUnreachable ： <裝置>無法到達那個房間。請將 <裝置/這些裝置>移到正確的樓層，然後再試一次。
hardwareFailure ： <裝置>有硬體問題。
inSoftwareUpdate ： <裝置>目前正在更新軟體。
isBypassed ： <裝置>目前已略過。
lowBattery : <裝置>電量不足。
motionDetected ： <裝置>偵測到動作。
needsPads : <裝置>需要更換電極片。
needsSoftwareUpdate ： <裝置>需要軟體更新。
needsWater ： <裝置>需要水。
networkJammingDetected ： <裝置> 的家用網路連線出現異常。
noIssuesReported ： <裝置>未回報任何問題。
roomsOnDifferentFloors : <裝置>無法移動到那些房間，因為那些房間位於其他樓層。
runCycleFinished ： <裝置>已完成運作。
securityRestriction ： <裝置>有安全限制。
smokeDetected ： 在 <住家名稱>偵測到煙霧。
tankEmpty : <device(s)> <has/have> <an empty tank/empty tanks>. Please fill <it/them> and try again.
usingCellularBackup ： <裝置>正在使用行動備份。
waterLeakDetected ： <裝置>偵測到漏水。

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