遷移至 Google Home 開發人員中心已完成。

本頁面由 Cloud Translation API 翻譯而成。

錯誤和例外狀況

本文件列出智慧住宅裝置正式支援的錯誤和例外狀況。請在意圖回應或通知 (如已實作) 中使用這些錯誤和例外狀況代碼，讓 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 ：「<device(s)> <is/are> 目前正在運轉中，所以我無法進行任何變更。
alreadyArmed : <裝置>已設為警戒模式。
alreadyAtMax : 「<裝置>已設為最高溫度。」
alreadyAtMin : 「<裝置>已設為最低溫度。」
alreadyClosed ：「<裝置> 已關閉。」
alreadyDisarmed ： <device(s)> <is/are> already disarmed.<裝置> 已解除武裝。
alreadyDocked : 「<裝置>已停靠在底座上。」
alreadyInState : <device(s)> <is/are> already in that state.
alreadyLocked : <device(s)> <is/are> 已鎖定。
alreadyOff : 「<裝置>已關閉。」<device(s)> <is/are> already off.
alreadyOn : 「<裝置>已開啟。」
alreadyOpen ： <裝置> 已開啟。<裝置>已開啟。
alreadyPaused : 「<裝置>」已暫停。
alreadyStarted : <裝置> 已啟動。
alreadyStopped : 「<裝置>已停止運作。」<is/are>
alreadyUnlocked : <device(s)> <is/are> already unlocked.<裝置>已解鎖。
ambiguousZoneName ： 抱歉，<裝置>無法辨識你指定的區域。請確認各個區域皆有專屬名稱，然後再試一次。
amountAboveLimit : 這樣會超出<裝置>所能負荷的數量。
appLaunchFailed ： 很抱歉，無法在 <裝置> 上啟動「<應用程式名稱>」。
armFailure : 無法啟動<裝置>。
armLevelNeeded ： 我不確定要將<裝置>設定在哪個層級。請試著說出「將<裝置>設為<低安全性>」或「將<裝置>設為<高安全性>」
authFailure : 我無法連上<裝置>。請直接使用這個裝置的應用程式，確認是否已設定完畢。
bagFull : <裝置>的袋子滿了，請清空後再試一次。
belowMinimumLightEffectsDuration ： 時間過短，下限為 5 分鐘。請再試一次。
belowMinimumTimerDuration ：我無法為<裝置>設定這麼短的時間，請再試一次。
binFull : <device(s)> <has/have> <a full bin/full bins>。
cancelArmingRestricted ： 很抱歉，我無法取消「<裝置>」的設防狀態。
cancelTooLate ： 抱歉，現在來不及取消了。請改用 <裝置> 或應用程式。
channelSwitchFailed : 抱歉，無法轉台到「<channel name>」頻道，請稍後再試。
chargerIssue : 抱歉，<device(s)> 的<充電器有問題/充電器有問題>。
commandInsertFailed ： 無法處理 <裝置> 的指令。
deadBattery : <device(s)> <has/have> <a dead battery/dead batteries>。
degreesOutOfRange : 指定角度超出「<裝置>」可活動的範圍。
deviceAlertNeedsAssistance : <device(s)> <has/have> an active alert and <need(s)> your assistance.
deviceAtExtremeTemperature : 「<裝置> 處於<極端溫度>」。
deviceBusy : 抱歉，<裝置>正在執行其他動作。
deviceCharging : 抱歉，<device(s)> 正在充電，因此無法執行這項動作 (ha_shared.ItsTheyre size=$item.devices.total_device_count)。
deviceClogged : 抱歉，<裝置>卡住了。
deviceCurrentlyDispensing : 「<裝置>正在供應東西」
deviceDoorOpen : 「<裝置>」的門已開啟，請關上門再試一次。
deviceHandleClosed : <device(s)> 上的控制代碼已關閉。請開啟控制代碼，然後再試一次。
deviceJammingDetected : <device(s)> <is/are> jammed.
deviceLidOpen ： <裝置> 的螢幕蓋已開啟，請關上螢幕蓋，然後再試一次。
deviceNeedsRepair : <device(s)> <need(s)> to be repaired. 請聯絡當地服務供應商。
deviceNotDocked : 抱歉，<裝置>不在充電座上。請將 <裝置>放回充電座，然後再試一次。
deviceNotFound : <device(s)> <is/are>n't available. 建議你重新設定 <它/它們>。
deviceNotMounted : 抱歉，<device(s)> 尚未安裝完畢，因此無法執行這個動作。
deviceNotReady : <device(s)> <is/are>n't ready.
deviceStuck : <device(s)> <is/are> stuck and needs your help.<裝置> <已/處於>卡住狀態，需要你的協助。
deviceTampered : <device(s)> <has/have> been tampered with.
deviceThermalShutdown : 抱歉，<裝置> 周遭環境的溫度過高/過低，因此已關閉。
directResponseOnlyUnreachable : <裝置>不支援遙控功能。
disarmFailure ：無法解除 <裝置> 的武裝。
discreteOnlyOpenClose : 抱歉，<裝置>只能完全開啟或完全關閉。
dispenseAmountAboveLimit : <device(s)> 無法供應這麼多的量。
dispenseAmountBelowLimit : <device(s)> 無法供應這麼少的量。
dispenseAmountRemainingExceeded : 「<裝置>」的「<分配項目>」不足，無法完成這項操作。
dispenseFractionalAmountNotSupported : 「<裝置>」無法分裝部分「<分裝項目>」。
dispenseFractionalUnitNotSupported : <device(s)> 無法以該單位供應非整數的<dispense item>。
dispenseUnitNotSupported : <device(s)> 不支援 <dispense item> 的該單位。
doorClosedTooLong : <裝置>的門關著一段時間了。請打開門確定一下裡面有放東西，然後再試一次。
emergencyHeatOn ： <device(s)> 目前處於緊急熱源模式，因此你必須手動調整。
faultyBattery : <device(s)> <has/have> <a faulty battery/faulty batteries>.
floorUnreachable ： <裝置>無法到達那個房間。請將 <裝置>移到正確的樓層，然後再試一次。
functionNotSupported : 抱歉，<裝置> <不>支援這項功能。
genericDispenseNotSupported : 我必須先知道你想供應的是什麼物品。請再試一次，並說出要供應的物品名稱。
hardError : 抱歉，發生錯誤，我現在無法控制你的家用裝置。
hardError : 抱歉，發生錯誤，我現在無法控制你的家用裝置。
inAutoMode : 「<裝置>」<已/目前>設為自動模式。你必須先將<it/them>切換到其他模式才能調整溫度。
inAwayMode : <device(s)> 目前已設為「不在家模式」。如要控制溫度控制器，請使用手機、平板電腦或電腦上的 Nest 應用程式，手動將溫度控制器切換成在家模式。
inDryMode : <device(s)> <is/are> currently set to dry mode. 你必須先將<it/them>切換到其他模式才能調整溫度。
inEcoMode : <device(s)> 目前設為節能模式。你必須先將<it/them>切換到其他模式才能調整溫度。
inFanOnlyMode : <device(s)> 目前設為僅限風扇模式。你必須先將<it/them>切換到其他模式才能調整溫度。
inHeatOrCool : <device(s)> <is/are>n't in heat/cool mode.
inHumidifierMode : <device(s)> <is/are> 目前設為加濕器模式。你必須先將<it/them>切換到其他模式才能調整溫度。
inOffMode ：「<裝置>目前已關閉。如要變更溫度，請切換到其他模式。」
inPurifierMode : <device(s)> <is/are> currently set to purifier mode. 你必須先將<it/them>切換到其他模式才能調整溫度。
inSleepMode : <device(s)> <is/are> in sleep mode. 請稍後再試。
inSoftwareUpdate ： <裝置>目前正在進行軟體更新。
lockFailure ：無法鎖定 <device(s)>。
lockedState : <device(s)> 目前已鎖定。
lockedToRange : 這個溫度不在「<裝置>」的鎖定範圍內。
lowBattery ： <裝置> 電池電量不足。
maxSettingReached : 「<裝置> 已設為最高設定」<is/are>。
maxSpeedReached : <裝置>已設為最高速度。
minSettingReached : 「<裝置> 已設為最低設定。」
minSpeedReached ： <裝置>已設為最低速度。
monitoringServiceConnectionLost ：「<裝置>已與監控服務中斷連線。」
needsAttachment ： 抱歉，<裝置>似乎缺少必要配件。請更換後再試一次。
needsBin : 抱歉，<裝置>似乎缺少集塵盒。請更換後再試一次。
needsPads : <device(s)> <need(s)> new pads.
needsSoftwareUpdate ： <裝置>需要軟體更新。
needsWater : <device(s)> <need(s)> water.
networkProfileNotRecognized ： 抱歉，我無法辨識<裝置>上的「<網路設定檔>」。
networkSpeedTestInProgress : 我正在測試「<網路>」的「<速度/速度>」。
noAvailableApp : 抱歉，<應用程式名稱> 似乎無法使用。
noAvailableChannel : 抱歉，沒有「<頻道名稱>」這個頻道。
noChannelSubscription : 抱歉，你目前並未訂閱「<頻道名稱>」頻道。
noTimerExists ： 抱歉，目前「<裝置>」沒有設定任何計時器。
notSupported ： 抱歉，<裝置> 不支援該模式。
obstructionDetected ： <device(s)> 偵測到障礙物。
offline , deviceOffline : 抱歉，<裝置>目前無法使用。
onRequiresMode ： 請指定要開啟的模式。
passphraseIncorrect ： 抱歉，PIN 碼似乎不正確。
percentOutOfRange : 很抱歉，我無法將 <裝置> 設為 <百分比>。
pinIncorrect ： (passphraseIncorrect)
rainDetected : 因為偵測到雨水，所以我沒有開啟「<裝置>」。
rangeTooClose ： <裝置> 的熱 • 冷範圍太小，請指定溫度範圍較寬的熱 • 冷值。
relinkRequired : 抱歉，帳戶出現錯誤。請透過「Google Home」或「Google 助理」應用程式重新連結 <裝置>。
remoteSetDisabled ：
- 選用參數 errorCodeReason
- currentlyArmed - 抱歉，保全系統已啟動，你必須透過 <裝置>或應用程式才能變更設定。
- remoteUnlockNotAllowed - 抱歉，我無法從遠端解鎖 <裝置>。
- remoteControlOff - 這個動作目前已停用。請啟用 <裝置>的遙控功能，然後再試一次。
- childSafetyModeActive - 如果兒童安全模式已啟用，就無法對 <裝置>執行這個動作。
roomsOnDifferentFloors : <裝置> 與這些房間位在不同樓層，因此無法前往。
safetyShutOff : <裝置>目前處於安全斷電模式，因此你必須手動調整。
sceneCannotBeApplied : 抱歉，無法套用至<裝置>。
securityRestriction : <device(s)> <has/have> a security restriction.
softwareUpdateNotAvailable ： 抱歉，<裝置>目前沒有可用的軟體更新。
startRequiresTime : 你必須先告訴我 <裝置> 要運轉多久，才能執行這個動作。
stillCoolingDown : <device(s)> <is/are> still cooling down.
stillWarmingUp : <device(s)> <is/are> still warming up.
streamUnavailable : 抱歉，<裝置>目前沒有畫面可供串流播放。
streamUnplayable : 抱歉，我目前無法透過「<裝置>」串流播放內容。
tankEmpty : <device(s)> <has/have> <an empty tank/empty tanks>。請填滿 <it/them>，然後再試一次。
targetAlreadyReached : 抱歉，這已經是目前溫度了。
timerValueOutOfRange ：無法為<裝置>設定這個長度的時間。
tooManyFailedAttempts ： 抱歉，嘗試失敗次數過多，請使用裝置上的應用程式完成這項動作。
transientError ： 抱歉，控制「<裝置>」時發生錯誤，請再試一次。
turnedOff , deviceTurnedOff : <裝置>目前已關閉。
unableToLocateDevice ：「我找不到 <裝置>。」 我找不到 <裝置>。
unknownFoodPreset : <device(s)> 不支援這項烹調預設設定。
unlockFailure ：無法解鎖 <device(s)>。
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 時發生非封鎖例外狀況 (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 : <裝置> <是否> 開啟。
deviceTampered : <device(s)> <has/have> been tampered with.
deviceUnplugged : <device(s)> <is/are> unplugged.
floorUnreachable ： <裝置>無法到達那個房間。請將 <裝置>移到正確的樓層，然後再試一次。
hardwareFailure : <裝置> <有/有>硬體問題。
inSoftwareUpdate ： <裝置>目前正在進行軟體更新。
isBypassed : <device(s)> <is/are> currently bypassed.
lowBattery ： <裝置> 電池電量不足。
motionDetected : <device(s)> <detect(s)> motion.
needsPads : <device(s)> <need(s)> new pads.
needsSoftwareUpdate ： <裝置>需要軟體更新。
needsWater : <device(s)> <need(s)> water.
networkJammingDetected ： <裝置> 的家用網路連線出現異常。
noIssuesReported : 「<裝置> 回報沒有問題。」
roomsOnDifferentFloors : <裝置> 與這些房間位在不同樓層，因此無法前往。
runCycleFinished : <device(s)> <has/have> finished running.
securityRestriction : <device(s)> <has/have> a security restriction.
smokeDetected : 在「<住家名稱>」偵測到煙霧。
tankEmpty : <device(s)> <has/have> <an empty tank/empty tanks>。請填滿 <it/them>，然後再試一次。
usingCellularBackup ： 「<裝置>正在使用行動備份。」
waterLeakDetected : <device(s)> <detect(s)> a water leak.

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