本文件列出智慧型家居裝置的官方支援錯誤和例外狀況。請在意圖回應中使用這些指定的錯誤和例外狀況代碼，或在通知中使用 (如果您已實作)，以便 Google 助理向使用者發出警報，告知與特定指令或裝置狀態相關的問題。如果回應包含錯誤的格式或 errorCode，Google 助理會向使用者顯示一般錯誤訊息，例如「很抱歉，裝置目前無法使用」。
錯誤
如果問題導致執行或查詢要求失敗，您應傳回錯誤代碼。舉例來說，如果門鎖卡住，無法上鎖或解鎖，應向使用者傳回有關此狀態的錯誤。
錯誤代碼可附加在裝置層級或全域層級。舉例來說，如果使用者擁有多盞由單一供應商提供的燈具，且這些燈具由中樞控制，當使用者要求關閉所有燈具時，如果單一燈具離線，供應商可能會傳回裝置層級錯誤；如果整個中樞離線，且無法控制任何燈具，供應商可能會傳回全域層級錯誤。如果所有裝置都處於離線狀態，使用全域層級或裝置層級錯誤並無差異。
您應當裝置離線時，在裝置行為的 5 分鐘內將 {"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" } } } }
執行回應
下列 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 ： 我只能將 <device(s)> 設為 <time period> 的時間長度
- action 無法使用 ： 很抱歉，我目前無法執行這個動作。
- actionUnavailableWhileRunning ： <device(s)> <is/are> 目前正在運作，因此我無法進行任何變更。
- 已經啟動 ： <device(s)> <is/are> 已經啟動。
- alreadyAtMax ： <裝置> <是/是> 已經設為最高溫度。
- alreadyAtMin ： <裝置> <是/是> 已經設為最低溫度。
- alreadyClosed ： <device(s)> <is/are> 已關閉。
- alreadyDisarmed ： <device(s)> <is/are> 已解除警報。
- alreadyDocked ： <device(s)> <is/are> 已連結。
- alreadyInState ： <device(s)> <is/are> 已處於該狀態。
- 已鎖定 ： <device(s)> <is/are> 已鎖定。
- 已經關閉 ： <device(s)> <is/are> 已關閉。
- alreadyOn ： <裝置> <是/是> 已開啟。
- 已開啟 ： <device(s)> <is/are> 已開啟。
- alreadyPaused ： <device(s)> <is/are> 已暫停。
- alreadyStarted ： <device(s)> <is/are> 已啟動。
- alreadyStopped ： <device(s)> <is/are> 已停止。
- 已解鎖 ： <device(s)> <is/are> 已解鎖。
- ambiguousZoneName ： 很抱歉，「<device(s)>」無法辨識正確的可用區。請確認各個區域皆有專屬名稱，然後再試一次。
- amountAboveLimit ： 超過 <device(s)> 所能負荷的數量。
- appLaunchFailed ：很抱歉，無法在 <device(s)> 上啟動「<應用程式名稱>」。
- arm 失敗 ： <device(s)> 無法啟動。
- armLevelNeeded ： 我不確定要將 <device(s)> 設為哪個層級，請試著說出「將 <裝置> 設為 <低安全性>」或「將 <裝置> 設為 <高安全性>」
- authFailure ： 我似乎無法連上 <device(s)>。請嘗試檢查應用程式，確認你的 <device/devices> <is/are> 已完全設定完畢。
- bagFull ： <device(s)> <has/have> <a full bag/full bags>。請<它/裝置>清空並重試。
- belowMinimumLightEffectsDuration ： 時間過短，下限為 5 分鐘。請再試一次。
- belowMinimumTimerDuration ： 我無法為 <device(s)> 設定這麼短的時間。請再試一次。
- binFull ： <device(s)> <has/have> <a full bin/full bins>。
- cancelArmingRestricted ： 抱歉，我無法取消為 <device(s)> 設定的警報狀態。
- cancelTooLate ： 很抱歉，取消期限已過，請改用 <device(s)> 或 app。
- channelSwitchFailed ： 很抱歉，無法切換至「<頻道名稱>」頻道，請稍後再試。
- chargerIssue ： 抱歉，<裝置> <有/有> <充電器問題/充電器問題>。
- commandInsertFailed ： 無法處理 <device(s)> 的指令。
- deadBattery ： <device(s)> <has/have> <a dead Battery/dead Battery>。
- degreesOutOfRange ： 指定的角度超出 <device(s)> 的範圍。
- deviceAlertNeedsAssistance ： <裝置> 有/有</>有效的警報，且 <需要>你的協助。
- deviceAtExtremeTemperature ： <裝置> <是/是>處於 <極端溫度/極端溫度>。
- deviceBusy ： 抱歉，<裝置>目前正在執行其他動作。
- deviceCharging ： 抱歉，由於(ha_shared.ItsTheyre size=$item.devices.total_device_count) 正在充電，因此 <device (s)> 無法執行這項動作。
- deviceClogged ： 抱歉，<裝置> 似乎卡住了。
- deviceCurrentlyDis 架 (裝置目前供應) ： <device(s)> 正在供應東西。
- deviceDoorOpen ： <裝置> 的門已開啟。請關閉門並重試。
- deviceHandleClosed ： <device(s)> 上的句柄已關閉。請開啟再試一次。
- deviceJammingDetected ： <device(s)> <is/are> jammed。
- deviceLidOpen ： <裝置> 的蓋子處於開啟狀態。請關閉蓋子，然後再試一次。
- device 需要維修 ： <device(s)> <need(s)>進行維修。請聯絡當地服務經銷商。
- deviceNotDocked ： 抱歉，<裝置> <未/未>處於充電座上。請將 <it/them> 插入座架，然後再試一次。
- deviceNotFound ： <device(s)> <is/are>n't available. 建議您重新設定<it/them>。
- device 未掛接 ： 很抱歉，<device(s)> 似乎尚未安裝 <it/they> <is/are>並未安裝，因此無法執行這個動作。
- deviceNotReady ： <device(s)> <is/are>n't ready。
- device 停滯 ： <device(s)> <is/are>無法解決，需要你的協助。
- deviceTampered ： <device(s)> <has/have> 已遭竄改。
- deviceThermalShutdown ： 抱歉，<裝置> 周遭環境的溫度過高/過低，因此已關閉。
- directResponseOnlyUnreachable ： <device(s)> <doesn't/don't> 支援遠端控制。
- disarmFailure ： <裝置> 無法解除警報。
- discreteOnlyOpenClose ： 很抱歉，「<device(s)>」只能完全開啟或關閉。
- dispenseAmountAboveLimit ： <device(s)> 無法供應這麼多的量。
- dispenseAmountBelowLimit ： <裝置> 無法供應這麼少的量。
- dispenseAmountRemainingExceeded ： <device(s)> 的 <dispense item> 不足，無法執行這項操作。
- dispenseFractionalAmountNotSupported ： <device(s)> 無法供應 <dispense item> 的零頭。
- dispenseFractionalUnitNotSupported ： <device(s)> 不支援 <dispense item> 的該單位小數。
- dispenseUnitNotSupported ： <device(s)> 不支援 <dispense item> 的單位。
- doorClosedTooLong ： 自 <device(s)> 上的門前已有一段時間未開啟，請打開門，確認裡面有東西，然後再試一次。
- 緊急熱源 ： <device(s)> <is/are> 處於緊急熱源模式，因此 <it/其他位置> 必須手動調整。
- faultyBattery ： <device(s)> <has/have> <a faulty battery/faulty batteries>.
- floorUnreachable ： <裝置>無法到達該房間。請將 <裝置>移到正確的樓層，然後再試一次。
- functionNotSupported ： 事實上，<device(s)> <not'/don't> 支援該功能。
- genericDispenseNotSupported ： 我必須知道你想供應什麼。請使用商品名稱再試一次。
- hardError ： 抱歉，發生錯誤，我無法控制你的家用裝置。
- hardError ： 抱歉，發生錯誤，我無法控制你的家用裝置。
- inAutoMode ： <device(s)> <is/are> 目前已設為自動模式。如要變更溫度，請將 <裝置> 切換至其他模式。
- inAwayMode ： <device(s)> <is/are> 目前已設為外出模式。如要控制溫度控制器，請使用手機、平板電腦或電腦上的 Nest 應用程式，手動將溫度控制器切換成在家模式。
- inDryMode ： <device(s)> <is/are> 目前已設為乾燥模式。你必須先切換到其他模式才能調整溫度
- inEcoMode ： <device(s)> <is/are>目前設為節能模式。你必須先切換到其他模式才能調整溫度
- inFanOnlyMode ： <device(s)> <is/are> 目前已設為風扇模式。你必須先切換到其他模式才能調整溫度
- inHeatOrCool ： <裝置> <是/是>未處於暖氣/冷氣模式。
- inHumidifierMode ： <裝置>目前設為加濕器模式。你必須先切換到其他模式才能調整溫度
- inOffMode ： <裝置>目前關閉。你必須先切換到其他模式，才能變更溫度。
- inPurifierMode ： <device(s)> <is/are> 目前設為空氣淨化模式。如要變更溫度，請將 <裝置> 切換至其他模式。
- inSleepMode ： <device(s)> <is/are>處於睡眠模式。請稍後再試。
- inSoftwareUpdate ： <device(s)> <is/are> 目前正在進行軟體更新。
- lockFailure ： <device(s)> 無法鎖定。
- lockedState ： <device(s)> <is/are> 目前已鎖定。
- lockedToRange ： 這個溫度不在 <device(s)> 的鎖定範圍內。
- 低電量 ： <device(s)> <has/have> 低電量。
- maxSettingReached ： <device(s)> <is/are> 已設為最高設定。
- maxSpeedReached ： <device(s)> <is/are> 已設為最高速度。
- minSettingReached ： <device(s)> <is/are> 已設為最低設定。
- minSpeedReached ： <device(s)> <is/are> 已設為最低速度。
- monitoringServiceConnectionLost ： <device(s)> <has/have> lost <its/their> connection to the monitoring service.
- needAttachment ： 很抱歉，<device(s)> <is/are> 似乎缺少必要的附件。請更換後再試一次。
- needsBin ： 抱歉，<device(s)> <is/are> 似乎缺少集塵盒。請更換後再試一次。
- needPads ： <device(s)> <need(s)> new pads.
- needSoftwareUpdate ： <device(s)> <need(s)> 軟體更新。
- needsWater ： <device(s)> <need(s)> water.
- networkProfileNotRecognized ： 抱歉，我無法辨識 <device(s)> 上的 "<network profile>"。
- networkSpeedTestInProgress ： 我正在測試 <network> <speed/speeds>>。
- noAvailableApp ： 抱歉，<應用程式名稱> 似乎無法使用。
- noAvailableChannel ： 抱歉，<頻道名稱> 似乎無法使用。
- no 頻道訂閱 ： 很抱歉，你目前並未訂閱「<頻道名稱>」頻道。
- noTimerExists ： 抱歉，目前 <device(s)> 沒有設定任何計時器。
- notSupported ： 很抱歉，<device(s)> 不支援該模式。
- obstructionDetected ： <裝置> 偵測到障礙物。
- offline , deviceOffline ： 抱歉，<device(s)> <is/are>目前無法使用。
- onRequiresMode ： 請指定要開啟的模式。
- 密碼不正確 ： 抱歉，PIN 碼似乎不正確。
- percentOutOfRange ： 抱歉，我無法將 <device(s)> 設為 <percent>。
- pinIncorrect ： (passphraseIncorrect)
- rainDetected ： 因為偵測到雨水，所以我沒打開 <裝置>。
- rangeTooClose ： <device(s)> 的熱 • 冷範圍太小，請指定溫度範圍較寬的熱 • 冷值。
- relinkRequired ： 很抱歉，您的帳戶似乎有問題。請透過 Google Home 或 Google 助理應用程式重新連結 <裝置>。
-
remoteSetDisabled
：
- 選用參數
errorCodeReason currentlyArmed- 抱歉，保全系統已啟動，你必須透過 <device(s)> 或應用程式才能變更設定。remoteUnlockNotAllowed- 很抱歉，我無法從遠端解鎖「<device(s)>」。remoteControlOff- 這項操作目前已停用。請啟用 <裝置> 的遙控功能，然後再試一次。childSafetyModeActive- 啟用兒童安全模式時，<device(s)>就無法執行這項操作。
- 選用參數
- roomsOnDifferentFloors ： <裝置>無法移動到那些房間，因為那些房間位於其他樓層。
- safetyShutOff ： <裝置> 目前處於安全斷電模式，因此你必須手動調整<裝置>。
- sceneCannotBeApplied ： 抱歉，無法套用 <device(s)>。
- security 限制 ： <device(s)> <has/have>安全性限制。
- softwareUpdateNotAvailable ： 很抱歉，<裝置> 沒有可用的軟體更新。
- startRequiresTime ： 你必須先告訴我要執行 <device(s)> 多久。
- stillCoolingDown ： <device(s)> <is/are> still cooling down。
- stillWarmingUp ： <device(s)> <is/are> still warming up。
- streamUnavailable ： 抱歉，目前無法從 <device(s)> 串流播放。
- 串流無法播放 ： 很抱歉，我目前無法透過 <device(s)> 播放串流。
- tankEmpty ： <裝置> <有/有著> <空的油箱/空的油箱>。請加滿 <油箱/油箱>，然後再試一次。
- targetAlreadyReached ： 抱歉，這已經是目前溫度了。
- timerValueOutOfRange ： <裝置> 無法設定為該時間長度。
- tooManyFailedAttempts ： 抱歉，嘗試次數過多。請使用裝置上的應用程式完成這項動作。
- transientError ： 很抱歉，控制 <device(s)> 時發生錯誤，請再試一次。
- turnedOff , deviceTurnedOff ： <裝置>目前已關閉。
- unableToLocateDevice ： 我無法找到 <device(s)>。
- unknownFoodPreset ： <裝置> 不支援該烹調預設設定。
- 解鎖失敗 ： 無法解鎖 <device(s)>。
- unpausableState ： <裝置>目前無法暫停。
- userCancelled ：ok
- valueOutOfRange ： <device(s)> 無法設為該溫度。
例外狀況
如果指令發生問題或顯示快訊，您應傳回例外狀況。指令可能會成功或失敗。
如果指令成功 (狀態 =「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 處理其他裝置的非封鎖例外狀況 (成功)
本例是啟動保全系統：好，啟動保全系統。前座車窗已開啟。
{ "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> <a full bag/full bags>。請<它/裝置>清空並重試。
- 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)> <is/are> open。
- deviceTampered ： <device(s)> <has/have> 已遭竄改。
- deviceUnplugged ： <device(s)> <is/are> unplugged。
- floorUnreachable ： <裝置>無法到達該房間。請將 <裝置>移到正確的樓層，然後再試一次。
- hardwareFailure ： <device(s)> <has/have> 硬體問題。
- inSoftwareUpdate ： <device(s)> <is/are> 目前正在進行軟體更新。
- isBypassed ： <device(s)> <is/are> 目前已略過。
- lowBattery ： <device(s)> <has/have> low battery。
- 動作偵測 ： <device(s)> <detect(s)> 動作。
- needsPads ： <device(s)> <need(s)> new pads。
- needSoftwareUpdate ： <device(s)> <need(s)> 軟體更新。
- 需要水 ： <device(s)> <need(s)> Water。
- networkJammingDetected ： <device(s)> 的家用網路連線出現異常。
- noIssuesReported ： <裝置> 未回報任何問題。
- roomOnDifferentFloors ： <device(s)>無法移動到這些房間，因為這些裝置位於不同樓層。
- runCycleFinished ： <device(s)> <has/have> 已完成執行。
- security 限制 ： <device(s)> <has/have>安全性限制。
- smokeDetected ： 在 <房屋名稱> 中偵測到煙霧。
- tankEmpty ： <裝置> <有/有著> <空的油箱/空的油箱>。請加滿 <油箱>，然後再試一次。
- 使用 CellularBackup ： <device(s)> <is/are>正在使用行動備份功能。
- waterLeakDetected ： <device(s)> <detect(s)> 偵測到水滲漏。