本文件列出智慧型家電的官方支援錯誤和例外狀況。請在意圖回應中使用這些指定的錯誤和例外狀況代碼，或在通知中使用 (如果您已實作)，以便 Google 助理向使用者發出警報，告知與特定指令或裝置狀態相關的問題。如果回應包含錯誤的格式或 errorCode，Google 助理會向使用者顯示一般錯誤訊息，例如「很抱歉，裝置目前無法使用」。
錯誤
當問題導致執行或查詢要求失敗時，您應傳回錯誤代碼。舉例來說，如果門鎖卡住，無法上鎖或解鎖，應向使用者傳回有關此狀態的錯誤。
錯誤代碼可附加至裝置層級或全域層級。舉例來說，如果使用者擁有多盞由單一供應商提供的燈具，且這些燈具由中樞控制，當使用者要求關閉所有燈具時，如果單一燈具離線，供應商可能會傳回裝置層級錯誤；如果整個中樞離線，且無法控制任何燈具，供應商可能會傳回全域層級錯誤。如果所有裝置都處於離線狀態，使用全域層級或裝置層級錯誤並無差異。
裝置離線時，您應在裝置行為發生後的 5 分鐘內，將 {"online": false} 回報至 Report State。
摘要說明：
- 全域層級錯誤：回應中的所有裝置都發生相同錯誤
- 區域層級錯誤：回應內容混雜，包含錯誤和成功案例
全域層級錯誤
下列 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" } }
裝置層級錯誤
查詢回應
下列 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 ： 我只能將 <device(s)> 設為 <time period> 的時間上限
- actionNotAvailable ： 抱歉，我目前無法執行這個動作。
- actionUnavailableWhileRunning ： <device(s)> <is/are> 目前正在運作，因此我無法進行任何變更。
- alreadyArmed ： <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> 已處於該狀態。
- alreadyLocked ： <裝置> <是/是>已上鎖。
- alreadyOff ： <裝置> <是/是> 已關閉。
- alreadyOn ： <裝置> <是/是> 已開啟。
- alreadyOpen ： <裝置> <是/是>已開啟。
- alreadyPaused ： <device(s)> <is/are> 已暫停。
- alreadyStarted ： <device(s)> <is/are> 已啟動。
- alreadyStopped ： <device(s)> <is/are> 已停止。
- alreadyUnlocked ： <device(s)> <is/are> 已解鎖。
- ambiguousZoneName ： 抱歉，<裝置>無法辨識你指定的區域。請確認各個區域皆有專屬名稱，然後再試一次。
- amountAboveLimit ： 超出 <device(s)> 所能負荷的數量。
- appLaunchFailed ： 抱歉，無法在 <device(s)> 上啟動 <app name>。
- armFailure ： <device(s)> 無法啟動。
- armLevelNeeded ： 我不確定要將 <device(s)> 設為哪個層級。試著說出「將<裝置>設為<低安全性>」或「將<裝置>設為<高安全性>」
- authFailure ： 我似乎無法連上 <device(s)>。請嘗試檢查應用程式，確認你的 <device/devices> <is/are> 已完全設定完畢。
- bagFull ： <裝置> <有/有著> <一個裝滿的袋子/裝滿的袋子>。請清空 <裝置>，然後再試一次。
- belowMinimumLightEffectsDuration ： 這比最短時間 5 分鐘還短。請再試一次。
- belowMinimumTimerDuration ： 我無法為 <device(s)> 設定這麼短的時間。請再試一次。
- binFull ： <device(s)> <has/have> <a full bin/full bins>。
- cancelArmingRestricted ： 抱歉，我無法取消為 <device(s)> 設定的警報狀態。
- cancelTooLate ： 抱歉，現在來不及取消了。請改用 <device(s)> 或應用程式。
- channelSwitchFailed ： 抱歉，無法切換至頻道 <頻道名稱>，請稍後再試。
- chargerIssue ： 抱歉，<裝置> <有/有> <充電器問題/充電器問題>。
- commandInsertFailed ： 無法處理 <device(s)> 的指令。
- deadBattery ： <device(s)> <has/have> <a dead battery/dead batteries>。
- degreesOutOfRange ： 指定的角度超出 <device(s)> 的範圍。
- deviceAlertNeedsAssistance ： <裝置> 有/有</>有效的警報，且 <需要>你的協助。
- deviceAtExtremeTemperature ： <裝置> <是/是>處於 <極端溫度/極端溫度>。
- deviceBusy ： 抱歉，<裝置>目前正在執行其他動作。
- deviceCharging ： 抱歉，由於(ha_shared.ItsTheyre size=$item.devices.total_device_count) 正在充電，因此 <device (s)> 無法執行這項動作。
- deviceClogged ： 抱歉，<裝置> 似乎卡住了。
- deviceCurrentlyDispensing ： <裝置> 正在供應東西。
- deviceDoorOpen ： <裝置> 的門已開啟。請關閉門並重試。
- deviceHandleClosed ： <device(s)> 上的句柄已關閉。請開啟再試一次。
- deviceJammingDetected ： <device(s)> <is/are> jammed。
- deviceLidOpen ： <裝置> 的蓋子處於開啟狀態。請關閉蓋子，然後再試一次。
- deviceNeedsRepair ： <裝置> <需要> 進行維修。請聯絡當地的服務供應商。
- deviceNotDocked ： 抱歉，<裝置> <未/未>處於充電座上。請先將 <裝置>放回充電座，然後再試一次。
- deviceNotFound ： <device(s)> <is/are>n't available. 建議你重新設定 <它/它們>。
- deviceNotMounted ： 抱歉，<device(s)> 尚未安裝，因此無法執行這個動作。
- deviceNotReady ： <device(s)> <is/are>n't ready。
- deviceStuck ： <裝置> <是/是> 卡住，需要你的協助。
- 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 ： <裝置> 的門關著一段時間了。請打開門確認一下裡面有放東西，然後再試一次。
- emergencyHeatOn ： <裝置> <是/是>處於緊急加熱模式，因此你必須手動調整<裝置>。
- faultyBattery ： <device(s)> <has/have> <a faulty battery/faulty batteries>.
- floorUnreachable ： <裝置>無法到達該房間。請將 <裝置>移到正確的樓層，然後再試一次。
- functionNotSupported ： 實際上，<device(s)> <不/不>支援這項功能。
- 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 ： <device(s)> <is/are> 目前設為加濕器模式。你必須先切換到其他模式才能調整溫度
- 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)> 的鎖定範圍內。
- lowBattery ： <device(s)> <has/have> low battery。
- 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.
- needsAttachment ： 抱歉，<device(s)> <is/are> 似乎缺少必要的附件。請更換後再試一次。
- needsBin ： 抱歉，<device(s)> <is/are> 似乎缺少集塵盒。請更換後再試一次。
- needsPads ： <device(s)> <need(s)> new pads。
- needsSoftwareUpdate ： <裝置> <需要> 軟體更新。
- needsWater ： <device(s)> <need(s)> water.
- networkProfileNotRecognized ： 抱歉，我無法辨識 <device(s)> 上的 "<network profile>"。
- networkSpeedTestInProgress ： 我正在測試 <network> <speed/speeds>>。
- noAvailableApp ： 抱歉，<應用程式名稱> 似乎無法使用。
- noAvailableChannel ： 抱歉，<頻道名稱> 似乎無法使用。
- noChannelSubscription ： 抱歉，你目前並未訂閱「<頻道名稱>」頻道。
- noTimerExists ： 抱歉，目前 <device(s)> 沒有設定任何計時器。
- notSupported ： 很抱歉，<device(s)> 不支援該模式。
- obstructionDetected ： <裝置> 偵測到障礙物。
- offline , deviceOffline ： 抱歉，<device(s)> <is/are>目前無法使用。
- onRequiresMode ： 請指定要開啟的模式。
- 密碼不正確 ： 抱歉，PIN 碼似乎不正確。
- percentOutOfRange ： 抱歉，我無法將 <device(s)> 設為 <percent>。
- pinIncorrect ： (passphraseIncorrect)
- rainDetected ： 因為偵測到雨水，所以我沒打開 <裝置>。
- rangeTooClose ： <裝置>的熱 • 冷範圍太小，請指定溫度範圍較寬的熱 • 冷值。
- relinkRequired ： 抱歉，帳戶似乎發生錯誤。請透過 Google Home 或 Google 助理應用程式重新連結 <裝置>。
-
remoteSetDisabled
：
- 選用參數
errorCodeReason currentlyArmed- 抱歉，保全系統已啟動，你必須透過 <device(s)> 或應用程式才能變更設定。remoteUnlockNotAllowed- 抱歉，我無法從遠端解鎖 <裝置>。remoteControlOff- 這項操作目前已停用。請啟用 <裝置> 的遙控功能，然後再試一次。childSafetyModeActive- 如果兒童安全模式已啟用，就無法對 <device(s)> 執行這個動作。
- 選用參數
- roomsOnDifferentFloors ： <裝置> 無法移動到這些房間，因為這些房間位於其他樓層。
- safetyShutOff ： <裝置> <是/是> 處於安全斷電模式，因此你必須手動調整<裝置>。
- sceneCannotBeApplied ： 抱歉，無法套用 <device(s)>。
- securityRestriction ： <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)>目前沒有可供串流播放的畫面。
- streamUnplayable ： 抱歉，我目前無法透過 <device(s)> 播放串流。
- tankEmpty ： <裝置> <有/有著> <空的油箱/空的油箱>。請加滿 <油箱/油箱>，然後再試一次。
- targetAlreadyReached ： 抱歉，這已經是目前溫度了。
- timerValueOutOfRange ： <裝置> 無法設定為該時間長度。
- tooManyFailedAttempts ： 抱歉，嘗試次數過多。請使用裝置上的應用程式完成這項動作。
- transientError ： 抱歉，控制 <device(s)> 時發生錯誤。請再試一次。
- turnedOff , deviceTurnedOff ： <裝置>目前已關閉。
- unableToLocateDevice ： 我無法找到 <device(s)>。
- unknownFoodPreset ： <裝置> 不支援該烹調預設設定。
- unlockFailure ： <device(s)> 無法解鎖。
- 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)> <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。
- motionDetected ： <device(s)> <detect(s)> motion。
- needsPads ： <device(s)> <need(s)> new pads。
- needsSoftwareUpdate ： <裝置> <需要> 軟體更新。
- needsWater ： <device(s)> <need(s)> water.
- networkJammingDetected ： <device(s)> 的家用網路連線出現異常。
- noIssuesReported ： <裝置> 未回報任何問題。
- roomsOnDifferentFloors ： <裝置> 無法移動到這些房間，因為這些房間位於其他樓層。
- runCycleFinished ： <device(s)> <has/have> 已完成執行。
- securityRestriction ： <device(s)> <has/have> 安全限制。
- smokeDetected ： 在 <房屋名稱> 中偵測到煙霧。
- tankEmpty ： <裝置> <有/有著> <空的油箱/空的油箱>。請加滿 <油箱/油箱>，然後再試一次。
- usingCellularBackup ： <device(s)> <is/are> 使用行動網路備份。
- waterLeakDetected ： <device(s)> <detect(s)> 偵測到水滲漏。