歡迎使用 Google Home 開發人員中心,探索全新功能,瞭解如何開發智慧住宅動作。注意:請繼續在「動作」控制台中建立動作。

錯誤和例外狀況

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

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

錯誤

如果問題導致執行或查詢要求失敗,您應傳回錯誤代碼。舉例來說,如果門鎖卡住了,無法鎖定或解鎖,則應傳回關於此狀態的錯誤。

錯誤代碼可在裝置層級或全域層級加入。例如,如果使用者有多個供應商的光源,且受到中樞控制,那麼當使用者要求關閉所有燈具時,如果單一光源離線,則供應商可能會傳回裝置層級錯誤;如果整個中樞離線,而且無法控制任何燈,則會傳回全域層級錯誤。如果所有裝置都離線,使用全域層級或裝置層級錯誤並沒有差別。裝置離線時,即使您傳回 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"
      }
    }
  }
}

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 小時的上限。請再試一次。
  • AboveMaxTimerDuration 我只能將 <device(s)> 設為 <time period>
  • actionNotAvailable很抱歉,我目前無法執行這項操作。
  • actionUnavailableRunningRunning <device(s)> <is/are> 目前正在執行,因此無法進行變更。
  • Armeded <device(s)> <is/are> 已啟動。
  • existAtMax<device(s)> <is/are> 已設為最高溫度。
  • existAtMin<device(s)> <is/are> 已設為最低溫度。
  • 已封閉 <device(s)> <is/are> 已停業。
  • existingDisarmed<device(s)> <is/are> 已解除解除。
  • 已插入 <device(s)> <is/are> 已插入座架。
  • existingInState <device(s)> <is/are> 處於該狀態。
  • 現已鎖定<device(s)> <is/are> 已鎖定。
  • OffOff <device(s)> <is/are> 已關閉。
  • OnOn <device(s)> <is/are> 已開啟。
  • 已開啟<device(s)> <is/are> 已經開啟。
  • 已暫停 <device(s)> <is/are> 已暫停。
  • 已開始 <device(s)> <is/are> 已啟動。
  • existingStopped <device(s)> <is/are> 已停止。
  • 已解鎖 <device(s)> <is/are> 已解鎖。
  • ambiguousZoneName 很抱歉,<device(s)> 無法辨識你指定的區域。請確認各個區域皆有專屬名稱,然後再試一次
  • amountAboveLimit 超過了 <device(s)> 可支援的內容。
  • appLaunchFailed很抱歉,無法在 <device(s)> 上啟動 <app name>。
  • armFailure <device(s)> 無法啟動。
  • armLevelneeded 我不確定該將 <device(s)> 設為哪個層級。請試著說出「將 <裝置> 設為低安全性」或「將 <裝置> 設為 <安全性>」>
  • authFailure 我無法連線至 <device(s)>。請試著檢查應用程式,確認<device/devices> <is/are> 已設定完畢。
  • FullFull <device(s)> <has/have> <a pack 袋/滿袋</>。請清空<it/them>,然後再試一次。
  • underMinimumLightEffectsDuration 少於 5 分鐘的下限。請再試一次。
  • UnderMinimumTimerDuration 我無法在這段時間內設定 <device(s)>。請再試一次。
  • binFull<device(s)> <has/have> <a bin bin/full bins>。
  • cancelArmingRestricted很抱歉,我無法取消配對 <device(s)>。
  • cancel TooLate很抱歉,現在取消的期限已過。請改用 <device(s)> 或應用程式。
  • channelSwitchFailed很抱歉,無法切換至「<channel name>」頻道,請稍後再試。
  • 充電器問題很抱歉,<device(s)> <has/have> <a 充電器問題/充電器問題>。
  • commandInsertFailed 無法處理 <device(s)> 的指令。
  • deadBattery <裝置> <has/have> <a 電池不足/電池沒電>。
  • degreeoutOfRange要求的 <device(s)> 值超出範圍。
  • deviceAlertneedsAssistance<device(s)> <has/have> 項未解決的快訊和 <need(s)> 您的協助。
  • deviceAtExtremeTemperature <device(s)> <is/are> (<a rerere 測溫/極端溫度)
  • deviceBusy 很抱歉,<device(s)> 目前正在執行某些動作。
  • deviceCharging很抱歉,<device(s)> 似乎無法執行這項作業,因為 (ha_shared.Itsersre 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)> <isn't/aren't> 已插入座架。請將 <it/them> 插入座架,然後再試一次。
  • deviceNotFound <device(s)> <is/are>無法使用。建議你重新設定 <it/them>。
  • deviceNotMounted 很抱歉,<device(s)> 無法安裝,因為 <it/他們> <未安裝
  • deviceNotReady <device(s)> <is/are>尚未準備好。
  • deviceStuck <device(s)> <is/are> 停滯不前,需要協助。
  • deviceTampered <device(s)> <has/have> 遭到竄改。
  • deviceThermalShutdown 很抱歉,<device(s)> 似乎因極端溫度而關閉。
  • directResponseOnlyUnreachable<device(s)> <不/不>> 支援遠端控制。
  • disarmFailure <device(s)> 無法解除。
  • screteOnlyOpenClose 很抱歉,<device(s)> 只能完全開啟或關閉。
  • DispenseAmountAboveLimit <device(s)> 無法供應這麼多的金額。
  • DispenseAmountBelowLimit <device(s)> 無法分配這麼少的金額。
  • DispenseAmountRemainingExceeded <device(s)> 的 <dispense item> 數量不足,無法執行這項動作。
  • DispenseFracativeAmountNotSupported <device(s)> 無法分配 <dispense item> 的分數。
  • depenseFracativeUnitNotSupported <device(s)> 不支援針對 <dispense item> 的單位部分進行分解。
  • dispenseUnitNotSupported <device(s)> 不支援針對 <dispense item> 的單位。
  • ClosedClosedTooLong <device(s)> 的車門已開了一段時間,請打開門確定一下裡面有放東西,然後再試一次
  • 如要緊急救援服務 在緊急加熱模式下,<is(s)> <is/are>,因此<it/他們>必須手動調整。
  • faultyBattery : <device(s)> <has/have> <a 有瑕疵的電池/電池故障>。
  • floorUnreachable<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 <裝置> <is/are> 目前正在進行軟體更新。
  • lockFailure無法鎖定 <device(s)>。
  • lockState:目前<device(s)> <is/are>已鎖定。
  • lockToRange這個溫度不在 <device(s)> 的鎖定範圍內。
  • lowBattery <device(s)> <has/have> 電量不足。
  • maxSettingReached<device(s)> <is/are> 已設為最高的設定。
  • maxSpeedReached<device(s)> <is/are> 已設為最高速度。
  • minSettingReached<device(s)> <is/are> 已設為最低的設定。
  • minSpeedReached<device(s)> <is/are> 已設為最低速度。
  • monitoringServiceConnection Loss <device(s)> <has/have> 與監控服務缺少 <its/the> 連線。
  • needAttachment 很抱歉,<device(s)> <is/are> 缺少必要的附件。請安裝後再試一次
  • needBin 很抱歉,<device(s)> <is/are> 缺少集塵盒。請安裝後再試一次
  • needPads<device(s)> <need(s)> 新的墊片。
  • needneedUpdate <device(s)> <need(s)> 軟體更新。
  • needWater<device(s)> <need(s)> 水。
  • networkProfileNotRecognized很抱歉,我無法辨識 <device(s)> 上的「<network profile>」。
  • networkSpeedTestInProgress我已經在 <network> <speed/speeds>> 中進行測試。
  • noAvailableApp很抱歉,<app name> 無法使用。
  • noAvailableChannel很抱歉,目前無法找到「<channel name>」頻道。
  • noChannelSubscription很抱歉,您目前並未訂閱 <channel name> 頻道。
  • notimerExists 很抱歉,<device(s)> 上沒有設定任何計時器。
  • 不支援很抱歉,該模式不支援 <device(s)>。
  • obstructionDetected<device(s)> 偵測到障礙物。
  • 離線、裝置離線很抱歉,<device(s)> <目前無法使用>
  • onOnsMode:指明要開啟的模式。
  • 通關密語錯誤 很抱歉,PIN 碼似乎不正確。
  • percentOutOfRange很抱歉,我無法將 <device(s)> 設為 <percent>。
  • pinIncorrect(passphraseIncorrect)
  • rainDetected 因為偵測到雨水,所以我無法開啟 <device(s)>。
  • scopeTooClose 如果 <device(s)> 的熱 • 冷範圍太小,請選擇最接近下方的溫度。
  • 需要重新連結 很抱歉,你的帳戶似乎出現錯誤。請透過 Google Home 或 Google 助理應用程式重新連結 <裝置>。
  • remoteSetDisabled
    • 選用參數 errorCodeReason
    • currentlyArmed - 很抱歉,由於保全系統已啟動,你必須使用 <device(s)> 或應用程式才能變更設定。
    • remoteUnlockNotAllowed - 很抱歉,我無法從遠端解鎖 <device(s)>。
    • remoteControlOff - 該動作目前已停用。請在 <device(s)> 上啟用遙控器,然後再試一次。
    • childSafetyModeActive - 在兒童安全模式啟用時,系統會為 <device(s)> 停用這個動作。
  • roomOnDifferenceFloors <device(s)> 位於那些樓層,因此無法進入這些房間。
  • safetyCloseOff
  • scapeCannotBeapplied很抱歉,無法套用 <device(s)>。
  • securityRestriction<device(s)> <has/have> 安全性限制。
  • softwareUpdateNotAvailable很抱歉,<device(s)> 沒有可用的軟體更新。
  • startRequiresTime 如要這麼做,您必須告訴我 <device(s)> 的執行時間。
  • tillCoolingDown <device(s)> <is/are> 仍在降溫。
  • tillWarmingUp <device(s)> <is/are> 仍在加熱。
  • streamUnavailable 很抱歉,目前無法從 <device(s)> 串流。
  • streamUnplayable 很抱歉,我目前無法從 <device(s)> 播放串流。
  • tankEmpty
  • targettargetreached 很抱歉,目前溫度已經是目前溫度。
  • timeValueOutOfRange<device(s)> 無法設定達到指定時間的時間。
  • Many ManyFailedtrys很抱歉,嘗試失敗次數過多,請前往裝置的應用程式完成這項操作。
  • transientError 抱歉,控制 <device(s)> 時發生錯誤。請再試一次。
  • 關閉 , deviceOffedOff <device(s)> <is/are>目前已關閉。
  • availableToLocateDevice我找不到 <device(s)>。
  • Unknown 未知 FoodPreset<device(s)> 不支援這個食物預設設定。
  • 解鎖 Failure <device(s)> 無法解鎖。
  • unpausableState:目前無法暫停<device(s)>
  • userCancelled確定
  • valueOutOfRange<device(s)> 無法設為這個溫度。

例外狀況

當指令與指令有關聯時,應傳回例外狀況。指令成功或失敗。

如果指令成功 (狀態 =「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)

以下範例是啟動保全系統的例子:好,開始啟動保全系統車窗打開了。

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

  • FullFull <device(s)> <has/have> <a pack 袋/滿袋</>。請清空<it/them>,然後再試一次。
  • binFull<device(s)> <has/have> <a bin bin/full bins>。
  • carbonMonoxideDetected 在 <house name> 中偵測到一氧化碳。
  • deviceAtExtremeTemperature <device(s)> <is/are> (<a rerere 測溫/極端溫度)
  • 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> 未插電。
  • floorUnreachable<device(s)> 無法到達該會議室。請將 <it/them> 移至正確的樓層,然後再試一次。
  • hardwareFailure<device(s)> <has/have> 硬體問題。
  • inSoftwareUpdate <裝置> <is/are> 目前正在進行軟體更新。
  • isBypassed:目前已略過 <device(s)> <is/are>
  • lowBattery <device(s)> <has/have> 電量不足。
  • MotionDetected<device(s)> <detect(s)> 動作。
  • needPads<device(s)> <need(s)> 新的墊片。
  • needneedUpdate <device(s)> <need(s)> 軟體更新。
  • needWater<device(s)> <need(s)> 水。
  • networkJammingDetected <device(s)> 的家用網路連線出現異常。
  • noIssuesReported<device(s)> 已回報任何問題。
  • roomOnDifferenceFloors <device(s)> 位於那些樓層,因此無法進入這些房間。
  • runCycleFinished<device(s)> <has/have> 已執行完畢。
  • securityRestriction<device(s)> <has/have> 安全性限制。
  • smokeDetected 在 <house name> 中偵測到煙霧。
  • tankEmpty
  • 使用 CellularBackup <device(s)> <is/are>使用行動網路備份。
  • waterLeakDetected <device(s)> <detect(s)> 漏水情形。