本文档列出了官方支持的智能家居设备错误和例外情况。请在 intent 响应或通知（如果您已实现）中使用这些指定的错误和异常代码，以便 Google 助理提醒最终用户注意与给定命令或设备状态相关的问题。如果响应中包含不正确的格式或 errorCode，Google 助理会向用户显示一般错误消息，例如“Sorry, device is not available now”。
错误
如果问题导致执行或查询请求失败，您应返回错误代码。例如，如果门锁卡住了，无法锁定或解锁，则应向用户返回与此状态有关的错误。
错误代码可以在设备级或全局级附加。例如，如果用户有来自同一提供商的多个灯具，并且这些灯具由一个集线器控制，那么当用户要求关闭所有灯具时，如果单个灯具处于离线状态，提供商可能会返回设备级错误；如果整个集线器处于离线状态且无法控制任何灯具，则提供商可能会返回全局级错误。如果所有设备都处于离线状态，则使用全局级错误或设备级错误没有区别。
当设备处于离线状态时，您应在设备出现相应行为后的 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" } } } }
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。
- aboveMaxLightEffectsDuration ： 这超过了 1 小时的最长持续时间。请重试。
- aboveMaxTimerDuration ： 我最多只能为 <time period> 设置 <device(s)>
- ActionNotAvailable ： 抱歉，我目前好像没法这样做。
- actionUnavailablewhileRunning ： <device(s)> <is/are> 目前正在运行，因此我无法进行任何更改。
- 已布防 ： <设备> 已布防。
- alreadyAtMax ： <device(s)> <is/are> already set to the maximum temperature.
- alreadyAtMin ： <设备> <已/正在> 设为最低温度。
- alreadyClosed ： <device(s)> <is/are> already closed.
- alreadyDisarmed ： <device(s)> <is/are> already disarmed.
- 已插入基座 ： <device(s)> <is/are> 已插入基座。
- alreadyInState ： <device(s)> <is/are> already in that state.
- alreadyLocked ： <device(s)> <is/are> already locked.
- alreadyOff ： <device(s)> <is/are> already off.
- alreadyOn ： <device(s)> <is/are> already on.
- alreadyOpen ： <device(s)> <is/are> 已打开。
- 已暂停 ： <device(s)> <is/are> 已暂停。
- alreadyStarted ： <device(s)> <is/are> already started.
- alreadyStopped ： <device(s)> <is/are> already stopped.
- alreadyUnlocked ： <device(s)> <is/are> already unlocked.
- ambiguousZoneName ： 抱歉，<device(s)> 无法识别您所指的区域。请确保您的区域具有唯一的名称，然后重试。
- amountAboveLimit ： 这超过了 <device(s)> 所能支持的范围。
- appLaunchFailed ： 抱歉，无法在 <device> 上启动 <app name>。
- armFailure ： <device(s)> 无法上报。
- armLevelNeeded ： 我不确定要将 <device(s)> 设为哪个级别。你可以试着说“将<设备>设为<低安全>”或“将<设备>设为<高安全>”
- authFailure ： 我似乎无法访问 <device(s)>。请尝试检查应用，确保您的 <device/devices> 已完整设置。
- bagFull ： <device(s)> <has/have> <a full bag/full bags>。请先把 <它/它们>清空，然后再试一次。
- belowMinimumLightEffectsDuration ： 这小于最短时长 5 分钟。请重试。
- belowMinimumTimerDuration ： 我没法给<设备>设定这么短的时间。请重试。
- binFull ： <设备> <有/具有> <满满的回收站/满满的回收站>。
- cancelArmingRestricted ： 抱歉，我无法取消<设备>的报警状态。
- cancelTooLate ： 抱歉，现在没法取消了。请改用“<device(s)>”或应用。
- channelSwitchFailed ： 抱歉，没能切换到频道 <channel name>。请稍后再试一次。
- chargerIssue ： 抱歉，<device(s)> <has/have> <a charger issue/charger issues>。
- commandInsertFailed ： 无法处理针对 <device(s)> 的命令。
- deadBattery ： <device(s)> <has/have> <a dead battery/dead batteries>。
- degreesOutOfRange ： 你要求的度数超出了 <device(s)> 的可调范围。
- deviceAlertNeedsAssistance ： <device(s)> <具有>一条有效提醒，<need(s)>您的协助。
- deviceAtExtremeTemperature ： <device(s)> <is/are> at <an extreme temperature/extreme temperatures>。
- deviceBusy ： 抱歉，<设备>现在好像在忙别的。
- deviceCharging ： 抱歉，<设备>好像没法执行这项操作，因为 (ha_shared.ItsTheyre size=$item.devices.total_device_count) 正在充电。
- deviceClogged ： 抱歉，<device(s)> 好像是卡住了。
- deviceCurrentlyDispensing ： <device(s)> 已经在进行分配了。
- deviceDoorOpen ： <device(s)> 上的门未关闭。请将其关好，然后重试。
- deviceHandleClosed ： <device> 上的句柄已关闭。请打开该句柄，然后重试。
- deviceJammingDetected ： <device(s)> <is/are> jammed.
- deviceLidOpen ： <设备> 的盖子处于打开状态。请关闭盖子，然后重试。
- deviceNeedsRepair ： <device(s)> <need(s)> to be repaired. 请与您当地的服务经销商联系。
- deviceNotDocked ： 抱歉，<设备>好像<未/未>接入基座。请将 <它/它们>放回底座，然后重试。
- deviceNotFound ： <device(s)> <is/are>n't available. 您可能需要再次尝试设置<it/them>。
- deviceNotMounted ： 抱歉，<设备>好像没法执行此操作，因为<它/它们>未安装。
- deviceNotReady ： <device(s)> <is/are>n't ready。
- deviceStuck ： <device(s)> <is/are> stuck and needs your help.
- deviceTampered ： <设备> <已/有>被篡改。
- deviceThermalShutdown ： 抱歉，<device(s)> 似乎因极端温度而关机。
- directResponseOnlyUnreachable ：<device(s)> <不支持远程控制。
- disarmFailure ： 无法关闭 <device(s)>。
- discreteOnlyOpenClose ： 抱歉，<device(s)> 只能全开或全关。
- dispenseAmountAboveLimit ： <device(s)> 无法分配这么大的量。
- dispenseAmountBelowLimit ： <device(s)> 无法分配这么小的金额。
- dispenseAmountRemainingExceeded ： <device(s)> 没有足够的 <dispense item> 来执行此操作。
- dispenseFractionalAmountNotSupported ：<device(s)> 无法分配 <dispense item> 的比例。
- dispenseFractionalUnitNotSupported ： <device(s)> 不支持为 <dispense item> 使用该单位的部分值。
- dispenseUnitNotSupported ： <device(s)> 不支持<dispense item> 的该单位。
- doorClosedTooLong ： <device(s)> 上的门已打开已有一段时间。请打开门并确保里面不是空的，然后再试一次。
- emergencyHeatOn ： <设备> <处于/位于> 应急供暖模式，因此<它/它们>必须手动进行调整。
- faultyBattery ： <device(s)> <has/have> <a faulty battery/faulty batteries>。
- floorUnreachable ： <device(s)> 无法覆盖该房间。请将 <它/它们>移到正确的楼层，然后重试。
- FunctionNotSupported ： 实际上，<device(s)> <doesn't/don't> support that functionality.
- genericDispenseNotSupported ： 我需要知道您要分发什么东西。请告诉我物品名称再试一次。
- hardError ： 抱歉，出了点问题，我无法控制你的家居设备。
- hardError ： 抱歉，出了点问题，我没法控制你的家居设备。
- inAutoMode ： <device(s)> <is/are> currently set to auto mode. 如需调节温度，您需要将<它/它们>切换到其他模式。
- inAwayMode ： <device(s)> <is/are> 目前已设为外出模式。如需控制温控器，您需要使用手机、平板电脑或计算机上的 Nest 应用将其手动切换到在家模式。
- inDryMode ： <device(s)> <is/are> 目前已设为除湿模式。如需调节温度，您需要将<它/它们>切换到其他模式。
- inEcoMode ： <device(s)> <is/are> currently set to eco mode. 如需调节温度，您需要将<它/它们>切换到其他模式。
- inFanOnlyMode ： <device(s)> <is/are> 目前已设为风扇模式。如需调节温度，你需要把<it/them>切换到其他模式。
- inHeatOrCool ： <device(s)> <未处于适温模式。
- inHumidifierMode ： <device(s)> <is/are> currently set to humidifier mode. 如需调节温度，您需要将<它/它们>切换到其他模式。
- inOffMode ： <设备> <处于/正在> 关闭状态。如需调节温度，您需要将<设备> 切换到其他模式。
- inPurifierMode ： <device(s)> <is/are> currently set to purifier mode. 如需调节温度，你需要把<it/them>切换到其他模式。
- inSleepMode ： <device(s)> <is/are> in sleep mode. 请稍后重试。
- inSoftwareUpdate ： <设备>目前正在进行软件更新。
- lockFailure ： 无法锁定<设备>。
- lockedState ： <device(s)> <is/are> currently locked.
- lockedToRange ： 此温度不在 <设备>的锁定范围内。
- 低电量 ： <device(s)> <has/have> low battery.
- maxSettingReached ： <device(s)> <is/are> already set to the highest setting.
- maxSpeedReached ： <device(s)> <is/are> 已设为最高速度。
- minSettingReached ： <device(s)> <is/are> already set to the lowest setting.
- minSpeedReached ： <device(s)> <已/正在> 设置为最低速度。
- monitoringServiceConnectionLost ： <device(s)> 与监控服务的连接已中断。
- needsAttachment ： 抱歉，<设备>好像缺少必要的附件。请更换它，然后重试。
- needsBin ： 抱歉，<设备>好像缺少垃圾箱。请更换它，然后重试。
- needsPads ： <device(s)> <need(s)> new pads。
- needsSoftwareUpdate ： <设备> <需要> 软件更新。
- needWater ： <device(s)> <need(s)> water.
- networkProfileNotConfirmd ： 抱歉，我在 <device(s)> 上无法识别“<network profile>”。
- 网络速度测试正在进行 ： 我正在测试 <network> <speed/speeds>>。
- noAvailableApp ： 抱歉，<app name> 似乎不可用。
- noAvailableChannel ： 抱歉，<channel name>频道似乎无法播放。
- noChannelSubscription ： 抱歉，您目前好像还没有订阅 <channel name> 频道。
- noTimerExists ： 抱歉，<device(s)> 上好像没有设置任何计时器。
- notSupported ： 抱歉，<device(s)>无法使用该模式。
- obstructionDetected ： <device(s)> 检测到障碍物。
- 离线, deviceOffline ： 抱歉，<device(s)> 现在似乎无法使用。
- onRequiresMode ： 请指定您要开启哪种模式。
- passphraseIncorrect ： 抱歉，这个 PIN 码好像不对。
- percentOutOfRange ： 抱歉，我无法将<设备>设置为<百分比>。
- pinIncorrect ： (passphraseIncorrect)
- rainDetected ： 因为检测到在下雨，所以我没有打开<设备>。
- 范围过小 ： 最高温和最低温的温差范围对 <设备>来说太小，请将温差范围调大一些。
- relinkRequired ： 抱歉，您的账号似乎出了点问题。请使用你的 Google Home 或 Google 助理应用重新关联 <device(s)>。
-
remoteSetDisabled
：
- 可选参数
errorCodeReason currentlyArmed- 抱歉，安防系统原本就处于开启状态，您需要使用 <device(s)> 或相关应用进行更改。remoteUnlockNotAllowed- 抱歉，我无法远程解锁<device>。remoteControlOff- 此操作目前已停用。请先在 <设备>上启用远程控制功能，然后再试一次。childSafetyModeActive- 儿童安全模式处于启用状态时，我没法对 <设备>执行这项操作。
- 可选参数
- roomsOnDifferentFloors ： <device(s)> 无法进入这些房间，因为它们位于不同楼层。
- safetyShutOff ： <device(s)> <is/are>处于安全关机模式，因此您必须手动调整 <it/them>。
- sceneCannotBeApplied ： 抱歉，无法应用 <device(s)>。
- securityRestriction ： <device(s)> <具有>一项安全限制。
- SoftwareUpdateNotAvailable ： 抱歉，<device(s)> 上没有可用软件更新。
- startTimeRequiresTime ： 为此，您需要告诉我您想让 <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 ： <device(s)> <has/have> <an empty tank/empty tanks>。请加满 <它/它们>，然后重试。
- targetAlreadyReached ： 抱歉，温控器好像原本就已经设为这个温度了。
- timerValueOutOfRange ： <device(s)> 无法设置为该时长。
- tooManyFailedAttempts ： 抱歉，尝试失败的次数过多。请前往设备的应用中完成此操作。
- transientError ： 抱歉，控制 <device(s)> 时出了点问题。请重试。
- 已关闭 ，deviceTurnedOff ： <设备> <当前>已关闭。
- unableToLocateDevice ： 我无法找到 <device(s)>。
- unknownFoodPreset ： <device(s)> 不支持该食物预设。
- unlockFailure ： <device(s)> 无法解锁。
- unpausableState ： <device(s)> 目前无法暂停。
- userCancelled ： ok
- valueOutOfRange ： <device(s)> 无法设为该温度。
异常
如果与命令相关联的问题或提醒，您应返回异常。命令可能会成功或失败。
如果命令成功（状态 =“SUCCESS”），请使用 StatusReport trait（对于目标设备以外的设备）或通过返回适当的 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。
- bagFull ： <device(s)> <has/have> <a full bag/full bags>。请先清空 <它/它们>，然后再试一次。
- binFull ： <设备> <有/具有> <满满的回收站/满满的回收站>。
- carbonMonoxideDetected ： <house name> 中检测到一氧化碳。
- deviceAtExtremeTemperature ： <device(s)> <is/are> <an extreme temperature/extreme temperatures>。
- deviceJammingDetected ： <device(s)> <is/are> jammed.
- deviceMoved ： <device(s)> <之前已移动>。
- deviceOpen ： <device(s)> <is/are> open。
- deviceTampered ： <设备> <已/有>被篡改。
- deviceUnplugged ： <设备>已拔下电源线。
- floorUnreachable ： <device(s)> 无法进入该房间。请将 <它/它们>移到正确的楼层，然后重试。
- hardwareFailure ： <设备> <有/存在>硬件问题。
- inSoftwareUpdate ： <设备>目前正在进行软件更新。
- isBypassed ： <device(s)> 目前已绕过。
- 低电量 ： <device(s)> <has/have> low battery.
- motionDetected ： <device(s)> <detect(s)> 动作。
- needsPads ： <device(s)> <need(s)> new pads。
- needsSoftwareUpdate ： <设备> <需要> 软件更新。
- needsWater ： <device(s)> <need(s)> water。
- networkJammingDetected ： 与 <device(s)> 的家庭网络连接不正常。
- noIssuesReported ： <device(s)> 报告了无问题。
- roomsOnDifferentFloors ： <设备>无法进入这些房间，因为它们位于不同楼层。
- runCycleFinished ： <device(s)> <has/have> 已完成运行。
- securityRestriction ： <device(s)> <has/have> a security restriction.
- smokeDetected ： <house name> 中检测到烟雾。
- tankEmpty ： <device(s)> <has/have> <an empty tank/empty tanks>。请加满 <它/它们>，然后重试。
- usingCellularBackup ： <device(s)> <is/are>使用备用移动网络。
- waterLeakDetected ： <device(s)> <detect(s)> 漏水。