本文档列出了智能家居设备的官方支持错误和异常。请在 intent 响应中或通知（如果您已实现）中使用这些给定错误和异常代码，以便 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" } }
设备级错误
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 ： 我只能将 <device> 设置为最长 <time period>
- ActionNotAvailable ： 抱歉，我目前好像没法这样做。
- ActionUnavailableWhileRunning ： <device(s)> <is/are> currently running, so I can't make any changes.
- alreadyArmed ： <device(s)> <is/are> already armed.
- alreadyAtMax ： <device(s)> <is/are> already set to the maximum temperature.
- alreadyAtMin ： <device(s)> <is/are> already set to the minimum temperature.
- alreadyClosed ： <device(s)> <is/are> already closed.
- alreadyDisarmed ： <device(s)> <is/are> already disarmed.
- alreadyDocked ： <device(s)> <is/are> already docked.
- 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> already open.
- alreadyPaused ： <device(s)> <is/are> already paused.
- 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 ： 我好像没法访问<设备>。请查看一下应用，确保<设备>已完成所有设置。
- 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)> <has/have> an active alert and <need(s)> your assistance.
- deviceAtExtremeTemperature ： <device(s)> <is/are> at <an extreme temperature/extreme temperatures>。
- deviceBusy ： 抱歉，<device(s)> 现在好像在忙别的。
- deviceCharging ： 抱歉，<设备>好像没法执行这项操作，因为 (ha_shared.ItsTheyre size=$item.devices.total_device_count) 正在充电。
- deviceClogged ： 抱歉，<device(s)> 好像是卡住了。
- deviceCurrentlyDispensing ： <device(s)> 已经在进行分配了。
- deviceDoorOpen ： <设备>的机盖未关好。请关闭机盖，然后重试。
- 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. 建议您尝试重新设置 <它/它们>。
- deviceNotMounted ： 抱歉，<设备>好像没法执行此操作，因为<它/它们>未安装。
- deviceNotReady ： <device(s)> <is/are>n't ready。
- deviceStuck ： <device(s)> <is/are> stuck and needs your help.
- deviceTampered ： <设备> <已/有>被篡改。
- deviceThermalShutdown ： 抱歉，<设备> 好像因极端温度关闭了。
- directResponseOnlyUnreachable ： <device(s)> <doesn't/don't> support remote control。
- disarmFailure ： 无法解除 <device(s)> 的报警。
- discreteOnlyOpenClose ： 抱歉，<device(s)> 只能全开或全关。
- dispenseAmountAboveLimit ： <device(s)> 无法分配这么大的量。
- dispenseAmountBelowLimit ： <device(s)> 没法分配这么小的量。
- dispenseAmountRemainingExceeded ： <device(s)> 没有足够的 <dispense item> 来执行此操作。
- dispenseFractionalAmountNotSupported ： <device(s)> 无法分次 dispense <dispense item>。
- dispenseFractionalUnitNotSupported ： <device(s)> 不支持为 <dispense item> 使用该单位的部分值。
- dispenseUnitNotSupported ： <device(s)> 不支持 <dispense item> 的该单位。
- doorClosedTooLong ： <设备> 的门已经开着有一段时间了。请打开门并确保里面不是空的，然后再试一次。
- emergencyHeatOn ： <device(s)> <is/are> in Emergency Heat Mode, so <it/they>'ll have to be adjusted by hand.
- 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)> 目前设为外出模式。如需控制温控器，您需要使用手机、平板电脑或计算机上的 Nest 应用将其手动切换到在家模式。
- inDryMode ： <device(s)> <is/are> currently set to dry mode. 如需调节温度，您需要将<它/它们>切换到其他模式。
- inEcoMode ： <device(s)> <is/are> currently set to eco mode. 如需调节温度，您需要将<它/它们>切换到其他模式。
- inFanOnlyMode ： <device(s)> <is/are> currently set to fan-only mode. 如需调节温度，您需要将<它/它们>切换到其他模式。
- inHeatOrCool ： <device(s)> 不在制热/制冷模式下。
- inHumidifierMode ： <device(s)> <is/are> currently set to humidifier mode. 如需调节温度，您需要将<它/它们>切换到其他模式。
- inOffMode ： <设备> <处于/正在> 关闭状态。如需调节温度，您需要将<设备> 切换到其他模式。
- inPurifierMode ： <device(s)> <is/are> currently set to purifier mode. 如需调节温度，您需要将<它/它们>切换到其他模式。
- 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)> <已/正在> 设置为最高速度。
- minSettingReached ： <device(s)> <is/are> already set to the lowest setting.
- minSpeedReached ： <device(s)> <已/正在> 设置为最低速度。
- monitoringServiceConnectionLost ： <device(s)> <has/have> lost <its/their> connection to the monitoring service.
- needsAttachment ： 抱歉，<设备>好像缺少必要的附件。请更换它，然后重试。
- needsBin ： 抱歉，<设备>好像缺少垃圾箱。请更换它，然后重试。
- needsPads ： <device(s)> <need(s)> new pads。
- needsSoftwareUpdate ： <设备> <需要> 软件更新。
- needsWater ： <device(s)> <need(s)> water。
- 网络资料未识别出来 ： 抱歉，我没法识别 <设备> 上的“<网络资料>”。
- 网络速度测试正在进行 ： 我正在测试 <network> <speed/speeds>>。
- noAvailableApp ： 抱歉，<app name> 似乎不可用。
- noAvailableChannel ： 抱歉，好像没法播放 <channel name> 频道。
- noChannelSubscription ： 抱歉，您目前好像还没有订阅 <channel name> 频道。
- noTimerExists ： 抱歉，<设备>上好像没有设置任何计时器。
- notSupported ： 抱歉，<device(s)> 不支持该模式。
- obstructionDetected ： <device(s)> 检测到障碍物。
- 离线 , deviceOffline ： 抱歉，<设备>目前似乎无法使用。
- onRequiresMode ： 请指定您要开启哪种模式。
- passphraseIncorrect ： 抱歉，这个 PIN 码好像不对。
- percentOutOfRange ： 抱歉，我无法将“<设备>”设置为“<百分比>”。
- pinIncorrect ： (passphraseIncorrect)
- rainDetected ： 因为检测到在下雨，所以我没有打开<设备>。
- 范围过小 ： 最高温和最低温的温差范围对 <设备>来说太小，请将温差范围调大一些。
- relinkRequired ： 抱歉，您的账号好像出了点问题。请使用 Google Home 或 Google 助理应用重新关联 <设备>。
-
remoteSetDisabled
：
- 可选参数
errorCodeReason currentlyArmed- 抱歉，安防系统原本就处于开启状态，您需要使用 <设备>或应用进行更改。remoteUnlockNotAllowed- 抱歉，我无法远程解锁<device>。remoteControlOff- 此操作目前已停用。请先在 <设备>上启用远程控制功能，然后再试一次。childSafetyModeActive- 儿童安全模式处于启用状态时，我没法对 <设备>执行这项操作。
- 可选参数
- roomsOnDifferentFloors ： <设备>无法进入这些房间，因为它们位于不同楼层。
- safetyShutOff ： <device(s)> <is/are> in Safety Shut-Off Mode, so <it/they>'ll have to be adjusted by hand.
- sceneCannotBeApplied ： 抱歉，无法应用 <device(s)>。
- securityRestriction ： <device(s)> <has/have> a security restriction.
- 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)> 时出了点问题。请重试。
- turnedOff , deviceTurnedOff ： <device(s)> 目前处于关闭状态。
- unableToLocateDevice ： 我无法找到<device(s)>。
- unknownFoodPreset ： <device(s)> 不支持该食物预设。
- unlockFailure ： <device(s)> 无法解锁。
- unpausableState ： <device(s)> 目前无法暂停。
- userCancelled ： ok
- valueOutOfRange ： <device(s)> 无法设为该温度。
异常
如果与命令相关联的问题或提醒，您应返回异常。该命令可能会成功或失败。
如果命令成功（状态 =“SUCCESS”），请使用 StatusReport trait（对于目标设备以外的设备）或通过返回适当的 exceptionCode（对于目标设备）报告异常。
例如，如果烘干机 lint 过滤器已满，用户仍然可以启动烘干机，但您可能需要提醒用户这种状态。同样，当设备电量不足但未耗尽时，您仍然可以执行命令，但应告知用户设备电量不足。
如果命令因异常而失败，状态应为“EXCEPTIONS”，并且应使用 StatusReport trait 报告异常。
与目标设备相关的非阻塞异常 (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> at <an extreme temperature/extreme temperatures>。
- deviceJammingDetected ： <device(s)> <is/are> jammed.
- deviceMoved ： <device(s)> <was/were> moved.
- deviceOpen ： <device(s)> <is/are> open。
- deviceTampered ： <设备> <已/有>被篡改。
- deviceUnplugged ： <device(s)> <is/are> unplugged.
- floorUnreachable ： <device(s)> 无法覆盖该房间。请将 <它/它们>移到正确的楼层，然后重试。
- hardwareFailure ： <设备>存在硬件问题。
- inSoftwareUpdate ： <设备>目前正在进行软件更新。
- isBypassed ： <device(s)> <is/are> currently bypassed.
- 低电量 ： <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。
- 网络干扰检测到 ： <设备>的家庭网络连接无法正常使用。
- noIssuesReported ： <device(s)> 报告了无问题。
- roomsOnDifferentFloors ： <设备>无法进入这些房间，因为它们位于不同楼层。
- runCycleFinished ： <device(s)> <has/have> finished running.
- securityRestriction ： <device(s)> <has/have> a security restriction.
- smokeDetected ： <house name> 中检测到烟雾。
- tankEmpty ： <device(s)> <has/have> <an empty tank/empty tanks>。请加满 <它/它们>，然后重试。
- usingCellularBackup ： <设备>正在使用移动网络备份。
- 水漏检测结果 ： <设备> <检测到> 水漏。