本文档列出了智能家居设备官方支持的错误和异常。请在意图响应或通知（如果您已实现）中使用这些给定的错误和异常代码，以便 Google 助理向最终用户发出与给定命令或设备状态相关的问题提醒。如果响应包含不正确的格式或 errorCode，Google 助理会向用户显示一般错误消息，例如“抱歉，设备目前不可用”。
错误
当问题导致执行或查询请求失败时，您应返回错误代码。例如，如果门锁卡住，无法上锁或解锁，则应向用户返回有关此状态的错误。
错误代码可以在设备级别或全局级别附加。 例如，如果用户有许多来自同一提供商的灯，并且这些灯由一个集线器控制，那么当用户要求关闭所有灯时，如果单个灯处于离线状态，提供商可能会返回设备级错误；如果整个集线器处于离线状态且无法控制任何灯，则提供商可能会返回全局级错误。如果所有设备都处于离线状态，则使用全局级错误或设备级错误没有区别。
总结：
- 全局级错误：响应中的所有设备都存在相同的错误
- 本地级错误：混合响应，包含错误和成功情况
全局级错误
以下 JSON 代码段展示了如何在 QUERY 或 EXECUTE 响应中返回全局级错误。
由于 hub 处于离线状态而导致全局级错误 deviceOffline 的示例：
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "errorCode": "deviceOffline", "status" : "ERROR" } }
由于 hub 正在更新而导致全局级错误 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> 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 ： 抱歉，未能在 <设备>上启动 <应用名称>。 提示：请验证 appId，并确保目标硬件支持该应用。
- armFailure ： <device(s)> 无法设防。
- armLevelNeeded : 我不确定要把<device(s)>设为哪个级别。请试着说“将<设备>设为<低安全性>”或“将<设备>设为<高安全性>”
- authFailure ： 我似乎无法连接到<device(s)>。你可以查看一下它的应用，确保<device/devices>已完成所有设置。
- bagFull : <device(s)> <has/have> <a full bag/full bags>. Please empty <it/them> and try again.
- belowMinimumLightEffectsDuration ： 时长低于 5 分钟的下限。请重试。
- belowMinimumTimerDuration : 我没法给<device(s)>设定这么短的时间。请重试。
- binFull ： <device(s)> <has/have> <a full bin/full bins>。
- cancelArmingRestricted : 抱歉，我无法取消<设备>的布防。
- cancelTooLate ： 抱歉，已错过取消截止时间。请改用 <设备>或应用。
- channelSwitchFailed : 抱歉，没能切换到 <频道名称>频道。请稍后再试一次。提示：请验证用户的频道名称/编号和订阅状态。
- chargerIssue ： 抱歉，<device(s)> 好像<has/have> <a charger issue/charger issues>。 提示：合作伙伴应调查硬件级遥测和电池健康度。
- commandInsertFailed ： 无法处理 <device(s)> 的命令。 提示：请调查数据库写入性能或内部命令排队逻辑。
- 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 : <device(s)> <is/are> at <an extreme temperature/extreme temperatures>.
- deviceBusy ： 抱歉，<device(s)>现在好像在忙别的。
- deviceCharging : 抱歉，<device(s)>正在充电，所以好像没法执行这项操作。
- deviceClogged : 抱歉，<device(s)>好像是卡住了。
- deviceCurrentlyDispensing ： <device(s)>已经在进行分配了。
- deviceDoorOpen ： <device(s)>的门开着。请关上门，然后重试。
- deviceHandleClosed ： <device(s)> 的把手已关闭。请打开把手，然后重试。
- deviceJammingDetected : <device(s)> <is/are> jammed.
- deviceLidOpen ： <device(s)> 的盖子已打开。请将其关闭，然后重试。
- deviceNeedsRepair ： <device(s)> <need(s)> to be repaired. 请与当地服务经销商联系。
- deviceNotDocked : 抱歉，<device(s)>好像没在基座上。请先让 <it/它们>回到基座，然后再试一次。
-
deviceNotFound
：
<device(s)> <is/are>n't available. 建议你尝试重新设置 <它/它们>。提示：确保您的后端始终与 Home Graph 保持同步。每当添加或移除设备时，调用
requestSync。 - 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 : 抱歉，<device(s)>好像因极端温度关闭了。
- directResponseOnlyUnreachable : <device(s)> <doesn't/don't> support remote control.
- disarmFailure ： 无法撤防<设备>。
- discreteOnlyOpenClose : 抱歉，<device(s)>只能完全打开或关闭。
- dispenseAmountAboveLimit : <device(s)> 没法分配这么大的量。
- dispenseAmountBelowLimit : <device(s)> 没法分配这么小的量。
- dispenseAmountRemainingExceeded : <device(s)> doesn't have enough <dispense item> to do that.
- dispenseFractionalAmountNotSupported ： <device(s)> can't dispense fractions of <dispense item>.
- dispenseFractionalUnitNotSupported : <device(s)> doesn't support fractions of that unit for <dispense item>.
- dispenseUnitNotSupported ： <device(s)> 不支持对<dispense item>使用该单位。
- doorClosedTooLong ： <device(s)>的门已经关着有一段时间了。请打开门并确保里面不是空的，然后再试一次。
- 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)> 不支持该功能。提示：确保您的 SYNC 响应准确反映设备的功能。
- genericDispenseNotSupported ： 我需要知道你想投放什么。请说出商品名称，然后重试。
- hardError ： 抱歉，出了点问题，我没法控制你的家居设备。
- hardError ： 抱歉，出了点问题，我没法控制你的家居设备。
- inAutoMode ： <device(s)> <is/are> currently set to auto mode. 如需更改温度，您需要将<it/它们>切换到其他模式。
- inAwayMode ： <device(s)> <is/are> currently set to 外出模式. 如需控制温控器，您需要使用手机、平板电脑或计算机上的 Nest 应用手动将其切换到在家模式。
- inDryMode ： <device(s)> <is/are> currently set to dry mode. 如需更改温度，您需要将<it/它们>切换到其他模式。
- inEcoMode ： <device(s)> <is/are> currently set to eco mode. 如需更改温度，您需要将<it/它们>切换到其他模式。
- inFanOnlyMode ： <device(s)>目前设置为仅风扇模式。如需更改温度，您需要将<it/它们>切换到其他模式。
- inHeatOrCool ： <device(s)> <is/are>n't in heat/cool mode.
- inHumidifierMode ： <device(s)> <is/are> currently set to humidifier mode. 如需更改温度，您需要将<it/它们>切换到其他模式。
- inOffMode ： <device(s)>目前处于关闭状态。如要更改温度，你需要将<it/them>切换到其他模式。
- inPurifierMode ： <设备>目前已设为净化模式。如需更改温度，您需要将<it/它们>切换到其他模式。
- inSleepMode ： <device(s)> <is/are> in 睡眠模式. 请稍后重试。
- inSoftwareUpdate ： <device(s)> 目前正在进行软件更新。
- lockFailure ： 无法锁定 <device(s)>。提示：检查锁具硬件是否存在物理卡阻、电量不足或电机故障。
- lockedState ： <device(s)> <is/are> currently locked.
- lockedToRange ： 该温度超出了 <设备>的锁定范围。
- lowBattery ： <device(s)> <has/have> low battery.
- maxSettingReached : <device(s)> <is/are> already set to the highest setting.
- maxSpeedReached : <device(s)> <is/are> already set to the maximum speed.
- minSettingReached : <device(s)>已经设为最低设置。
- minSpeedReached : <device(s)> <is/are> already set to the minimum speed.
- monitoringServiceConnectionLost ： <device(s)> <has/have> lost <its/their> connection to the monitoring service.
- needsAttachment ： 抱歉，<device(s)> 好像缺少必要的附件。请先更换它，然后再试一次。
- needsBin : 抱歉，<device(s)>好像缺少箱子。请先更换它，然后再试一次。
- needsPads ： <device(s)> 需要更换新垫。
- needsSoftwareUpdate ： <device(s)> 需要更新软件。
- needsWater ： <device(s)>需要浇水。
- networkProfileNotRecognized ： 抱歉，我无法识别“<设备>”上的“<网络配置文件>”。 提示：验证配置文件名称字符串是否与 SYNC 响应中支持的配置文件匹配。
- networkSpeedTestInProgress ： 我已经在测试<网络><速度>了。
- noAvailableApp ： 抱歉，<app name> 似乎无法使用。
- noAvailableChannel : 抱歉，好像没法播放<频道名称>频道。
- noChannelSubscription : 抱歉，你目前好像还没有订阅<频道名称>频道。
- noTimerExists ： 抱歉，<device(s)>上好像没有设置任何定时器。
- notSupported ： 抱歉，<device(s)> 不支持该模式。
- obstructionDetected ： <device(s)> 检测到障碍物。
- offline , deviceOffline : 抱歉，<device(s)> 好像现在无法使用。
- onRequiresMode ： 请指定您要开启哪种模式。
- passphraseIncorrect : 抱歉，这个 PIN 码好像不对。
- percentOutOfRange : 抱歉，我无法将<设备>设置为 <percent>。
- pinIncorrect ： (passphraseIncorrect)
- rainDetected : 因为检测到在下雨，所以我没有打开<device(s)>。
- rangeTooClose : <device(s)>的供暖/制冷温度范围太窄。请选择相差更大的温度。
- relinkRequired : 抱歉，你的账号好像出了点问题。请使用 Google Home 或 Google 助理应用重新关联 <设备>。 提示：请确保在刷新令牌永久失效时，您的服务器会返回此代码。
-
remoteSetDisabled
：
- 可选参数
errorCodeReason currentlyArmed- 抱歉，安防系统原本就处于开启状态，你需要使用 <设备>或应用进行更改。remoteUnlockNotAllowed- 抱歉，我无法远程解锁<设备>。remoteControlOff- 目前已停用这项操作。请先在 <设备>上启用远程控制，然后再试一次。childSafetyModeActive- 儿童安全模式处于启用状态时，我没法对 <设备>执行这项操作。
- 可选参数
- roomsOnDifferentFloors ： <device(s)> 到不了这些房间，因为它们位于不同楼层。
- safetyShutOff ： <device(s)>处于安全关闭模式，因此必须手动调整。
- sceneCannotBeApplied : 抱歉，无法应用<设备>。提示：检查合作伙伴云端用户场景的内部健康状况。
- securityRestriction ： <device(s)> <has/have> a security restriction.
- softwareUpdateNotAvailable : 抱歉，<device(s)>没有可用的软件更新。
- startRequiresTime : 要完成这项操作，你需要先告诉我你想让<device(s)>运行多长时间。
- stillCoolingDown ： <device(s)> <is/are> still cooling down.
- stillWarmingUp ： <device(s)> <is/are> still warming up.
- streamUnavailable : 抱歉，<device(s)> 似乎目前无法播放直播。
- streamUnplayable ： 抱歉，我目前无法播放来自<设备>的直播。提示：验证 WebRTC/HLS 信令，并确保直播网址有效。
- tankEmpty : <device(s)> <has/have> <an empty tank/empty tanks>. Please fill <it/them> and try again.
- targetAlreadyReached : 抱歉，这好像已经是当前温度了。
- timerValueOutOfRange : 无法为<设备>设置该时长。
- tooManyFailedAttempts ： 抱歉，尝试失败次数过多。请转到设备的应用中完成此操作。
- transientError ： 抱歉，控制 <设备>时出了点问题。请重试。提示：这些错误最常见的表现形式是与设备或服务的连接中断。如果无法打开与服务器的新连接，也会发生这种情况。
- turnedOff , deviceTurnedOff : <device(s)> <is/are> off right now.
- unableToLocateDevice : 我无法找到<device(s)>。 提示：请检查设备的本地连接性（Wi-Fi/蓝牙）。
- unknownFoodPreset : <device(s)> 不支持这个食物预设。
- unlockFailure ： 无法解锁 <device(s)>。提示：调查硬件卡住、电池电量不足或 PIN 码输入无效等问题。
- unpausableState : 目前没法暂停<device(s)>。
- userCancelled ： ok
- valueOutOfRange ： 无法将<设备>设置为该温度。
在线和离线状态报告
设备离线后，您应在设备出现相应行为后的 5 分钟内将 <code{"online": code="" dir="ltr" false}<="" translate="no"> 报告给报告状态。相反，当设备恢复在线状态时，您应在设备出现相应行为后的 5 分钟内将 <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 : <device(s)> <has/have> <a full bag/full bags>. Please empty <it/them> and try again.
- binFull ： <device(s)> <has/have> <a full bin/full bins>。
- 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 ： <device(s)> <has/have> been tampered with.
- deviceUnplugged : <device(s)> <is/are> unplugged.
- floorUnreachable ： <device(s)> 到不了这个房间。请把它/它们移到正确的楼层，然后再试一次。
- hardwareFailure ： <device(s)> <has/have> a hardware problem.
- inSoftwareUpdate ： <device(s)> 目前正在进行软件更新。
- isBypassed ： <device(s)> 目前已被绕过。
- lowBattery ： <device(s)> <has/have> low battery.
- motionDetected ： <device(s)> 检测到移动。
- needsPads ： <device(s)> 需要更换新垫。
- needsSoftwareUpdate ： <device(s)> 需要更新软件。
- needsWater ： <device(s)>需要浇水。
- networkJammingDetected ： <device(s)> 的家庭网络连接无法正常运行。
- noIssuesReported ： <device(s)> 未报告任何问题。
- roomsOnDifferentFloors ： <device(s)> 到不了这些房间，因为它们位于不同楼层。
- runCycleFinished ： <device(s)> <has/have> finished running.
- securityRestriction ： <device(s)> 存在安全限制。
- smokeDetected ： 在 <住宅名称>中检测到烟雾。
- tankEmpty : <device(s)> <has/have> <an empty tank/empty tanks>. Please fill <it/them> and try again.
- usingCellularBackup ： <device(s)> 正在使用备用移动网络。
- waterLeakDetected ： <设备>检测到漏水。