本文档列出了智能家居设备的正式支持的错误和异常。请在 intent 响应或通知（如果您已实现通知）中使用这些给定的错误和异常代码，以便 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 : 我只能为 <device(s)> 设置最长 <time period> 的使用时间
- actionNotAvailable : 抱歉，我目前好像没法这样做。
- actionUnavailableWhileRunning : <device(s)> 目前正在运行，所以我没法做任何更改。
- alreadyArmed : <device(s)> <is/are> already armed.
- alreadyAtMax : <device(s)> 已设为最高温度。
- 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)> 已暂停。
- 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(s)> 上启动 <app name>。
- armFailure ： 无法启动<设备>。
- 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 : 抱歉，我无法取消对<device(s)>的布防。
- cancelTooLate : 抱歉，现在没法取消了。请改为使用 <设备> 或应用。
- 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 : 抱歉，<device(s)> 正在充电，所以好像没法执行这项操作。
- deviceClogged : 抱歉，<device(s)> 好像卡住了。
- deviceCurrentlyDispensing : <device(s)> 已经在进行分配了。
- deviceDoorOpen : <device(s)> 的机盖未关好。请关好机盖，然后重试。
- deviceHandleClosed : <device(s)> 上的句柄已关闭。请打开该句柄，然后重试。
- deviceJammingDetected : <device(s)> <is/are> jammed.
- deviceLidOpen : <device(s)> 的机盖处于打开状态。请关闭机盖，然后重试。
- deviceNeedsRepair : <设备>需要维修。请联系您的当地服务经销商。
- deviceNotDocked : 抱歉，<device(s)> 好像没在基座上。请将 <设备/它们>放入基座，然后重试。
- deviceNotFound : <device(s)> 不可用。<is/are>建议您重新设置 <它/它们>。
- deviceNotMounted : 抱歉，<device(s)> 没有装载，所以好像没法执行这项操作。
- deviceNotReady : <device(s)> 尚未准备就绪。
- deviceStuck : <device(s)> <is/are> stuck and needs your help.
- deviceTampered : <device(s)> <has/have> been tampered with.
- deviceThermalShutdown : 抱歉，<device(s)> 好像因极端温度关闭了。
- directResponseOnlyUnreachable : <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 : <device(s)> <is/are> in Emergency Heat Mode, so <it/they>'ll have to be adjusted by hand.
- faultyBattery : <设备> <有/有> <一块/多块>故障电池。
- floorUnreachable : <device(s)> 到不了这个房间。请将 <设备>移到正确的楼层，然后重试。
- functionNotSupported : 实际上，<device(s)> <doesn't/don't> 支持这项功能。
- genericDispenseNotSupported : 我需要知道你要分发什么东西。请告诉我物品名称再试一次。
- hardError : 抱歉，出了点问题，我没法控制你的家居设备。
- hardError : 抱歉，出了点问题，我没法控制你的家居设备。
- inAutoMode : <device(s)> <is/are> currently set to auto mode. 如需更改温度，您需要将<设备>切换到其他模式。
- inAwayMode : <device(s)> <is/are> currently set to away mode. 如需控制温控器，您需要使用手机、平板电脑或计算机上的 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)> 目前已设为加湿模式。如需更改温度，您需要将<设备>切换到其他模式。
- inOffMode : <设备>目前处于关闭状态。如需调节温度，您需要将<设备>切换到其他模式。
- inPurifierMode : <device(s)> <is/are> currently set to purifier mode. 如需更改温度，您需要将<设备>切换到其他模式。
- inSleepMode : <device(s)> <is/are> in sleep mode. 请稍后重试。
- inSoftwareUpdate : <device(s)> <is/are> currently in a software update.
- lockFailure : 无法锁定 <device(s)>。
- lockedState : <device(s)> 目前处于锁定状态。
- lockedToRange : 该温度不在 <device(s)> 锁定的范围内。
- lowBattery ： <device(s)> 电量不足。
- maxSettingReached : <device(s)> 已设置为最高设置。
- maxSpeedReached : <device(s)> 已设置为最大速度。
- minSettingReached : <device(s)> 已设置为最低设置。
- minSpeedReached : <device(s)> 已设置为最低速度。
- monitoringServiceConnectionLost : <device(s)> <has/have> lost <its/their> connection to the monitoring service.
- needsAttachment : 抱歉，<device(s)> 好像缺少必要的附件。请先更换它，然后再试一次。
- needsBin : 抱歉，<device(s)> 好像缺少集尘盒。请先更换它，然后再试一次。
- needsPads : <设备> 需要更换新垫片。
- needsSoftwareUpdate : <device(s)> <need(s)> a software update.
- needsWater : <device(s)> <need(s)> water.
- networkProfileNotRecognized : 抱歉，我无法识别 <device(s)> 上的“<network profile>”。
- networkSpeedTestInProgress : 我已经在测试<network>的<speed/speeds>了。
- noAvailableApp : 很抱歉，<应用名称>似乎无法使用。
- noAvailableChannel : 抱歉，好像没法播放 <频道名称> 频道。
- noChannelSubscription : 抱歉，您目前好像还没有订阅 <频道名称> 频道。
- noTimerExists : 抱歉，<device(s)> 上好像没有设置任何计时器。
- notSupported : 抱歉，<device(s)> 不支持该模式。
- obstructionDetected ： <device(s)> 检测到障碍物。
- offline , deviceOffline : 抱歉，<device(s)>目前好像无法使用。
- onRequiresMode : 请指定要开启的模式。
- passphraseIncorrect : 抱歉，这个 PIN 码好像不对。
- percentOutOfRange : 很抱歉，我无法将 <device(s)> 设置为 <percent>。
- pinIncorrect : (passphraseIncorrect)
- rainDetected : 因为检测到在下雨，所以我没有打开<device(s)>。
- rangeTooClose : 最高温和最低温的温差范围对 <device(s)>来说太小，请将温差范围调大一些。
- relinkRequired : 抱歉，您的账号好像出了点问题。请使用 Google Home 或 Google 助理应用重新关联 <device(s)>。
-
remoteSetDisabled
:
- 可选参数
errorCodeReason currentlyArmed- 抱歉，安防系统原本就处于开启状态，你需要使用 <device(s)>或应用进行更改。remoteUnlockNotAllowed- 抱歉，我无法远程解锁<device(s)>。remoteControlOff- 目前已停用这项操作。请在 <device(s)> 上启用远程控制功能，然后重试。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)> 上没有可用的软件更新。
- startRequiresTime : 为此，你需要先告诉我你想让<device(s)>运行多长时间。
- stillCoolingDown : <device(s)> <is/are> still cooling down.
- stillWarmingUp : <device(s)> <is/are> still warming up.
- streamUnavailable : 抱歉，目前好像没法传输来自 <device(s)> 的画面。
- streamUnplayable : 抱歉，我现在没法播放来自<设备>的画面。
- tankEmpty : <device(s)> <has/have> <an empty tank/empty tanks>. Please fill <it/them> and try again.
- targetAlreadyReached : 抱歉，温控器好像原本就已经设为这个温度了。
- timerValueOutOfRange ： 无法将<device(s)>设置为该时长。
- tooManyFailedAttempts : 抱歉，尝试失败的次数过多。请前往设备的应用完成相应操作。
- transientError : 抱歉，控制 <设备>时出了点问题。请重试。
- turnedOff , deviceTurnedOff : <device(s)> 目前处于关闭状态。
- unableToLocateDevice : 我无法找到<device(s)>。
- unknownFoodPreset : <device(s)> 不支持该食物预设。
- unlockFailure : 无法解锁 <device(s)>。
- unpausableState : <device(s)> 目前无法暂停。
- userCancelled ： ok
- valueOutOfRange : 无法将<device(s)>设为该温度。
在线和离线状态报告
设备离线后，您应在设备出现相应行为后的 5 分钟内将 <code{"online": code="" dir="ltr" false}<="" translate="no"> 报告给 Report State。相反，当设备恢复到在线状态时，您应在设备出现相应行为后的 5 分钟内将 <code{"online": code="" dir="ltr" translate="no" true}<=""> 报告给 Report State。 每当设备恢复在线状态时，合作伙伴都应使用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 特征报告异常。
有关目标设备的非阻塞异常 (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>. Please empty <it/them> and try again.
- binFull : <device(s)> <has/have> <a full bin/full bins>。
- carbonMonoxideDetected : <住宅名称>中检测到一氧化碳。
- deviceAtExtremeTemperature : <device(s)> <is/are> at <an extreme temperature/extreme temperatures>。
- deviceJammingDetected : <device(s)> <is/are> jammed.
- deviceMoved : <device(s)> <was/were> moved.
- deviceOpen : <设备>已打开。
- deviceTampered : <device(s)> <has/have> been tampered with.
- deviceUnplugged : <device(s)> 已拔下。
- floorUnreachable : <device(s)> 到不了这个房间。请将 <设备>移到正确的楼层，然后重试。
- hardwareFailure ： <device(s)> 存在硬件问题。
- inSoftwareUpdate : <device(s)> <is/are> currently in a software update.
- isBypassed : <device(s)> 目前处于绕过状态。
- lowBattery ： <device(s)> 电量不足。
- motionDetected : <device(s)> <detect(s)> motion.
- needsPads : <设备> 需要更换新垫片。
- needsSoftwareUpdate : <device(s)> <need(s)> a software update.
- 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 ： <住宅名称>中检测到烟雾。
- tankEmpty : <device(s)> <has/have> <an empty tank/empty tanks>. Please fill <it/them> and try again.
- usingCellularBackup : <device(s)> <is/are> using cellular backup.
- waterLeakDetected ： <设备>检测到漏水。