錯誤和例外狀況

本文件列出官方支援的智慧住宅裝置錯誤和例外狀況。請在意圖回應或通知中使用這些指定的錯誤和例外狀況代碼 (如果您已實作此代碼)，這樣 Google 助理就能通知使用者特定指令或裝置狀態相關問題。如果回應包含不正確的格式或 errorCode，Google 助理會為使用者提供一般錯誤訊息，例如「很抱歉，目前尚無法使用 device」。

錯誤

如果問題導致執行或查詢要求失敗，您應傳回錯誤代碼。舉例來說，如果門鎖卡住，無法鎖定或解鎖，則應向使用者傳回有關這個狀態的錯誤訊息。

您可以將錯誤代碼附加至裝置層級或全域層級。舉例來說，如果使用者有多個來自某個供應商的燈具，且這些燈具是由一個供應商控制，當使用者要求關掉所有燈具時，供應器可能會在單燈離線時傳回裝置層級錯誤；如果整個中樞裝置離線且無法控制任何燈具，則可能會傳回全域層級錯誤。如果所有裝置都處於離線狀態，使用全域層級或裝置層級錯誤並無差異。在裝置離線時，即使傳回 deviceOffline 錯誤代碼，仍應在 reportState 中回報 {"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 小時的最長時間。請再試一次。
  • 超過 maxTimerDuration ： 我最多只能設定 <device(s)>，最長 <時間範圍>
  • actionNotAvailable ： 很抱歉，我目前無法執行這個動作。
  • actionUnavailable 執行中 ： <device(s)> <is/are> 目前正在執行，因此無法進行任何變更。
  • alreadyArmed ： <device(s)> <is/are> 已啟動。
  • 已經在最大溫度 ： <device(s)> <is/are> 已設為最高溫度。
  • alreadyAtMin ： <device(s)> <is/are> 已設為最低溫度。
  • 已關閉 ： <device(s)> <is/are> 已關閉。
  • 已經解除 ： <device(s)> <is/are> 已經解除。
  • 已放上座架 ： <device(s)> <is/are> 已插上座架。
  • alreadyInState ： <device(s)> <is/are> 先前已在這個狀態中。
  • alreadyLocked ： <device(s)> <is/are> 已鎖定。
  • alreadyOff ： <device(s)> <is/are> 已關閉。
  • alreadyOn ： <device(s)> <is/are> 已開啟。
  • alreadyOpen ： <device(s)> <is/are> 已開啟。
  • 已暫停 ： <device(s)> <is/are> 已暫停。
  • 已開始 ： <device(s)> <is/are> 已開始。
  • 已經停止 ： <device(s)> <is/are> 已停止。
  • 已解鎖 ： <device(s)> <is/are> 已解鎖。
  • biguousZoneName ： 很抱歉，<device(s)> 無法識別你指定的可用區。請確認各個可用區均有專屬名稱，然後再試一次。
  • amountAboveLimit ： 這超出了 <device(s)> 的功能。
  • appLaunchFailed ： 很抱歉，無法在 <device(s)> 上啟動 <應用程式名稱>。
  • armFailure ： 無法啟動 <device(s)>。
  • armLevel 如需 ： 我不確定要將 <device(s)> 設為哪個層級。請試著說出「將 <裝置> 設為 <低安全性>」或「將 <裝置> 設為「<高安全性>」
  • authFailure ： 我無法連線到「<device(s)>」。請查看應用程式，確認 <裝置/裝置> <is/are> 的設定完畢。
  • packFull ： <device(s)> <擁有/擁有> <滿袋/整袋> 。請將 <it/them>留空，然後再試一次。
  • lowLightLightEffectsDuration ： 這小於 5 分鐘的最短持續時間。請再試一次。
  • 低於 MinimumTimerDuration ： 暫時無法設定 <device(s)>，請再試一次。
  • binFull ：<device(s)> <has/have> <a full bin/full bins>。
  • cancelArmingRestricted ： 很抱歉，我無法取消啟動 <device(s)> 的轉換動作。
  • cancelTooLate ： 很抱歉，取消時間已過。請改用 <device(s)> 或應用程式。
  • channelSwitchFailed ： 很抱歉，無法切換至「<頻道名稱>」頻道，請稍後再試。
  • 充電器問題 ： 抱歉，看起來像是 <device(s)> <has/have> <a Charge issue/charger issues>。
  • commandInsertFailed ： 無法處理 <device(s)>的指令。
  • deadBattery ： <device(s)> <has/have> <a Batterys ird Battery/dead batteries>。
  • degreeOutOfRange ： 要求的角度超出 <device(s)> 的範圍。
  • deviceAlert 需要協助 ： <device(s)> <has/擁有> 未解除的快訊，因此 <need(s)>您的協助。
  • deviceAtExtremeTemperature ： <device(s)> <is/are> 度為 <極端溫度/極端溫度>。
  • deviceBusy ： 很抱歉，<device(s)> 似乎已在執行其他操作。
  • deviceCharging ： 很抱歉，<device(s)> 似乎無法執行這項動作，因為 (ha_shared.Its 他們 re size=$item.devices.total_device_count) 充電。
  • deviceClogged ： 很抱歉，<device(s)> 似乎已經關閉。
  • deviceCurrentlyDispensing ： <device(s)> 目前已供應東西。
  • deviceDoorOpen ： 門在 <device(s)> 上開啟了門，請關上並再試一次。
  • deviceHandleClosed ： 帳號代碼在 <device(s)> 上已關閉。請開啟帳號代碼，然後再試一次。
  • deviceJammingDetected ： <device(s)> <is/are> 卡住。
  • deviceLidOpen ： <device(s)> 的機蓋已開啟。請闔上裝置，然後再試一次。
  • deviceNeedsRepair ： <device(s)> <need(s)> 需要維修。請與您的當地服務經銷商聯絡。
  • deviceNotDocked ： 很抱歉，<device(s)> 似乎<is't/aren't 已放上座架。請將 <it/them>插入座架，然後再試一次。
  • deviceNotFound ： <device(s)> <is/are> 無法使用。建議你重新設定 <it/them>。
  • deviceNotMounted ： 很抱歉，「<device(s)>」似乎無法掛載，因為<it/這些> <is/are>尚未掛載。
  • deviceNotReady ： <device(s)> <is/are>尚未就緒。
  • device 停滯 ： <device(s)> <is/are> 停滯不前，需要你的協助。
  • deviceTampered ： <device(s)> <has/have> 遭竄改
  • deviceThermalShutdown ： 很抱歉，<device(s)> 因溫度極端而關機。
  • directResponseOnlyUnconnected ： <device(s)> <doesn't/don'>支援遠端控制系統。
  • disarmFailure ： <device(s)>無法解除。
  • discreteOnlyOpenClose ： 很抱歉，<device(s)> 只能完全開啟或關閉。
  • dispenseAmountAboveLimit ： <device(s)> 無法超量供應。
  • dispenseAmountBelowLimit ： <device(s)> 無法供應這麼小的量。
  • DipenseAmountRemainingExceeded ： <device(s)> 的 <dispense item> 不足，該怎麼辦？
  • dispenseFractionalAmountNotSupported ： <device(s)> 無法分配 <dispense item> 的小數。
  • DipenseFractionalUnitNotSupported ： <device(s)> 不支援以該單位為單位的 <dispense item>。
  • dispenseUnitNotSupported ：<device(s)>不支援該單位的 <dispense item>。
  • gateClosedTooLong ： <device(s)>的車門已經開啟一段時間。請打開車門並確認車內有東西，然後再試一次。
  • EmergencyHeatOn : <device(s)> 處於緊急熱源模式，因此<it/這些> 必須手動調整。
  • faultyBattery ： <device(s)> <具有/有> <電池故障/電池故障>。
  • FloUnConnected ： <device(s)> 無法到達該房間。請將 <it/them>移至正確的樓層，然後再試一次。
  • functionNotSupported ： 實際上，<device(s)> <不支援/未> 支援該項功能。
  • genericDispenseNotSupported ： 我必須瞭解您要供應的類型。請使用商品名稱再試一次。
  • HarError ： 很抱歉，出了點小狀況，所以我無法控制你的住宅裝置。
  • HarError ： 很抱歉，出了點小狀況，所以我無法控制你的住宅裝置。
  • inAutoMode ： <device(s)> <is/are> 目前設為自動模式。如要調整溫度，必須將<it/them>切換為其他模式。
  • inAwayMode ： <device(s)> <is/are> 目前設為外出模式。如要控制溫度控制器，請使用手機、平板電腦或電腦上的 Nest 應用程式，手動將溫度控制器切換成在家模式。
  • inDryMode ： <device(s)> <is/are> 目前設為乾燥模式。如要調整溫度，必須將<it/them>切換為其他模式。
  • inEcoMode ： <device(s)> <is/are> 目前設為節能模式。如要調整溫度，必須將<it/them>切換為其他模式。
  • inFanOnlyMode ：<device(s)> <is/are>目前設為僅限風扇模式。如要調整溫度，必須將<it/them>切換為其他模式。
  • inHeatOrCool ： <device(s)> <is/are> 未處於熱/冷模式。
  • inHumidifierMode ： <device(s)> <is/are> 目前設為加濕器模式。如要調整溫度，必須將<it/them>切換為其他模式。
  • inOffMode ： <device(s)> <is/are> 目前處於關閉狀態。如要變更溫度，必須將 <it/them> 切換為其他模式。
  • inPurifierMode ： <device(s)> <is/are> 目前設為淨化模式。如要調整溫度，必須將<it/them>切換為其他模式。
  • inSleepMode ： 處於睡眠模式時，<device(s)> <is/are>。請稍後再試。
  • inSoftwareUpdate ： <device(s)> <is/are> 目前正在進行軟體更新。
  • LockFailure ： 無法鎖定 <device(s)>。
  • lockState ： <device(s)>目前鎖定中。
  • lockToRange ： 目前的溫度不在 <device(s)> 的鎖定範圍內。
  • 低電量 ： <device(s)> <擁有/擁有> 低電量。
  • maxSettingReached ： <device(s)>已將<is/are>設為最高的設定。
  • maxSpeedReached ： <device(s)>已設為最高速度。
  • minSettingReached ： <device(s)> <is/are> 已設為最低值。
  • minSpeedReached ： <device(s)> <is/are> 已經設為最低速度了。
  • monitoringServiceConnection Loss ： <device(s)> <has/have> 對監控服務的連線已中斷。
  • 需要附件 ： 很抱歉， <device(s)> 似乎缺少必要的附件。請更換後再試一次。
  • needBin ： 很抱歉，<device(s)> <is/are> 似乎缺少集點。請更換後再試一次。
  • needPads ： <device(s)> <need(s)> 新衛生棉。
  • needSoftwareUpdate ： <device(s)> <need(s)> 軟體更新。
  • needWater ： <device(s)> <need(s)>水。
  • networkProfileNotReco 已識別 ： 很抱歉，我在 <device(s)> 上無法辨識「<網路設定檔>」。
  • networkSpeedTestInProgress ：我已測試 <network> <speed/speeds>>。
  • noAvailableApp ： 很抱歉，<應用程式名稱> 似乎無法使用。
  • noAvailableChannel ： 抱歉，您似乎無法購買「<channel name>」頻道。
  • noChannelSubscription ： 很抱歉，你目前並未訂閱「<channel name>」頻道。
  • noTimerExists ： 很抱歉，<device(s)> 上似乎沒有任何設定任何計時器。
  • 不支援 ： 很抱歉，<device(s)> 不支援這個模式。
  • 偵測到障礙物 ：<device(s)>偵測到障礙物。
  • 離線 , deviceOffline ： 很抱歉，<device(s)> 目前無法使用。
  • onRequiresMode ：請指定你要開啟的模式。
  • 通關密語不正確 ： 很抱歉，PIN 碼似乎不正確。
  • %OutOfRange ： 很抱歉，我無法將 <device(s)> 設為 <percent>。
  • PIN 碼不正確 ：(passphrase 正確)
  • rainDetected ： 我沒有打開 <device(s)>，因為偵測到雨水。
  • rangeTooClose ： <device(s)> 的熱冷範圍範圍距離太近。請選擇較大的溫度。
  • 重新連結必要 ： 很抱歉，您的帳戶似乎發生問題。請透過 Google Home 或 Google 助理應用程式重新連結 <device(s)>。
  • RemoteSetDisabled ：
    • 選用參數 errorCodeReason
    • currentlyArmed - 很抱歉，安全機制已啟動，你必須使用「<device(s)>」或應用程式才能變更設定。
    • remoteUnlockNotAllowed - 很抱歉，我無法從遠端解鎖 <device(s)>。
    • remoteControlOff - 這個動作目前已停用。請在 <device(s)> 上啟用遙控器，然後再試一次。
    • childSafetyModeActive - 當兒童安全模式啟用時，<device(s)> 就無法執行這項操作。
  • roomOnDifferenceFloors <device(s)> 無法移動到這些房間，因為那些房間位於不同樓層。
  • SafetyShutOff ： 安全關機模式設為 <device(s)> <is/are>，因此你必須手動調整「<裝置>」<it/>。
  • sceneCannotBeApplied ： 很抱歉，無法套用 <device(s)>。
  • securityRestriction ： <device(s)> <具有/擁有>安全性限制。
  • SoftwareUpdateNotAvailable ： 很抱歉，<device(s)> 沒有可用的軟體更新。
  • startRequiresTime ： 不過，你必須先告訴我要執行「<device(s)>」的時間長度。
  • tillCoolingDown ： <device(s)> <is/are>仍在降溫。
  • svearmingUp ： <device(s)> <is/are>仍在準備中。
  • streamUnavailable ： 很抱歉，<device(s)> 目前無法串流播放。
  • streamUnplayable ： 很抱歉，我目前無法播放「<device(s)>」的串流內容。
  • tankEmpty ： <device(s)> <has/擁有> <空水槽/空水槽>。請填寫 <it/them>，然後再試一次。
  • 目標已達成 ： 抱歉，目前溫度已經是目前溫度。
  • watchValueOutOfRange ： <device(s)> 無法在該時間範圍內設定。
  • Too ManyFailed Numbers (失敗) ：很抱歉，嘗試失敗次數過多。請開啟裝置上的應用程式，完成這項操作。
  • transientError ： 很抱歉，控制 <device(s)> 時發生錯誤，請再試一次。
  • Off , deviceTurnedOff ： 目前已關閉<device(s)> <is/are>。
  • 找不到「FindDevice」 ： 我無法找到 <device(s)> 的位置。
  • UnknownFoodPreset ： <device(s)> 不支援這項食物預設設定。
  • UnlockFailure ： 無法解鎖 <device(s)>。
  • unpausableState ： 目前無法暫停<device(s)>。
  • userCancelled ： 確定
  • valueOutOfRange ： <device(s)> 無法設為這個溫度。

例外狀況

當指令發生問題或快訊時，您應傳回例外狀況。指令可能會成功或失敗。

如果指令執行成功 (status = "SUCCESS")，請使用 StatusReport 特徵 (針對目標以外的裝置) 回報例外狀況，或傳回適當的 exceptionCode (適用於目標裝置)。

舉例來說，如果烘衣機 Lint 畫面滿格，使用者仍可啟動烘衣機，但您可能需要警告使用者此狀態。同樣地，如果裝置的電量較低，且使用的電量偏低，您還是可以執行指令，但應告知對方裝置電量過低。

如果指令因例外狀況而失敗，狀態應為「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)

以下示範如何啟動保全系統：Ok，正在啟動保全系統。前窗打開了。

{
  "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。

  • packFull ： <device(s)> <擁有/擁有> <滿袋/整袋> 。請將 <it/them>留空，然後再試一次。
  • binFull ：<device(s)> <has/have> <a full bin/full bins>。
  • carbonMonoxideDetected ： 在 <house name> 偵測到一氧化碳。
  • deviceAtExtremeTemperature ： <device(s)> <is/are> 度為 <極端溫度/極端溫度>。
  • deviceJammingDetected ： <device(s)> <is/are> 卡住。
  • deviceMoved ： <device(s)> <was/were>已移動。
  • deviceOpen ： <device(s)> <is/are> 已開啟。
  • deviceTampered ： <device(s)> <has/have> 遭竄改
  • deviceUnplugged ： <device(s)> <is/are> 未接上電源。
  • FloUnConnected ： <device(s)> 無法到達該房間。請將 <it/them>移至正確的樓層，然後再試一次。
  • HardwareFailure ： <device(s)> <有/擁有>硬體問題。
  • inSoftwareUpdate ： <device(s)> <is/are> 目前正在進行軟體更新。
  • 已略過 ： 目前已略過<device(s)> <is/are>。
  • 低電量 ： <device(s)> <擁有/擁有> 低電量。
  • MotionDetected ： <device(s)> <detect(s)>動作。
  • needPads ： <device(s)> <need(s)> 新衛生棉。
  • needSoftwareUpdate ： <device(s)> <need(s)> 軟體更新。
  • needWater ： <device(s)> <need(s)>水。
  • networkJammingDetected ： 連至 <device(s)> 的家用網路連線無法正常運作。
  • noIssuesReported ： <device(s)> 未回報任何問題。
  • roomOnDifferenceFloors <device(s)> 無法移動到這些房間，因為那些房間位於不同樓層。
  • runCycleFinished ： <device(s)> <搭載> 已執行完畢。
  • securityRestriction ： <device(s)> <具有/擁有>安全性限制。
  • 煙霧偵測 ： 系統在 <house name> 中偵測到煙霧。
  • tankEmpty ： <device(s)> <has/擁有> <空水槽/空水槽>。請填寫 <it/them>，然後再試一次。
  • usingCellularBackup ： <device(s)> <is/are> 正在使用行動備份功能。
  • WaterLeakDetected ： <device(s)> <detect(s)>漏水。