错误和异常

本文档列出了官方支持的智能家居设备错误和异常。请在 intent 响应或通知(如果您已实现)中使用这些指定的错误和异常代码,以便 Google 助理提醒最终用户与特定命令或设备状态相关的问题。如果响应包含错误的格式或 errorCode,Google 助理会向用户显示一条宽泛的错误消息,例如“抱歉,device 目前无法使用”。

错误数

如果某个问题导致执行或查询请求失败,您应返回错误代码。例如,如果门锁被卡住,无法上锁或解锁,则应向用户返回有关此状态的错误。

您可以在设备级别或全局级别附加错误代码。例如,如果用户的很多灯都来自一个提供方并且由 hub 控制,那么当用户要求关闭所有灯时,提供程序可能会返回设备级错误(如果其中一台灯处于离线状态),或者返回全局级错误(如果用户的整个 hub 处于离线状态且所有灯都处于离线状态)。如果所有设备都处于离线状态,使用全局级错误或设备级错误没有区别。当设备离线时,即使您返回 deviceOffline 错误代码,也应在 reportState 中报告 {"online": false} 状态。

总结:

  • 全局级错误:响应中的所有设备都存在相同的错误
  • 本地级别错误:混合响应,包含错误和成功案例

全局级错误

以下 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。

  • aboveMinimumLightEffectsDuration 超过最长持续时间(1 小时)。请重试。
  • aboveMinimumTimerDuration : 我只能设置最多 <timeperiod>的 <device(s)>
  • actionNotAvailable 抱歉,我目前似乎无法执行此操作。
  • actionUnavailablewhileRunning <device(s)> <is/are> 目前正在运行,因此我无法进行任何更改。
  • alreadyArmed <device(s)> <is/are> alreadyed.
  • alreadyAtMax <device(s)> <is/are>已设置为最高温度。
  • alreadyAtMin <device(s)> <is/are> 已设置为最低温度。
  • alreadyClosed <device(s)> <is/are> 已关闭。
  • alreadyDisarmed <device(s)> <is/are> 已关闭。
  • 已插入基座 <device(s)> <is/are>已插入基座。
  • alreadyInState <device(s)> <is/are> 已处于该状态。
  • alreadyLocked <device(s)> <is/are>已锁定。
  • alreadyOff <device(s)> <is/are> 已关闭。
  • alreadyOn <device(s)> <is/are> 已开启。
  • alreadyOpen <device(s)> <is/are> 已打开。
  • alreadypause <device(s)> <is/are> 已经暂停。
  • alreadyStarted <device(s)> <is/are> 已启动。
  • alreadyStopped <device(s)> <is/are>已停止。
  • alreadyUnlocked <device(s)> <已>已解锁。
  • ambiguousZoneName 抱歉,<device(s)> 无法识别您指的是哪一个可用区。请确保您的区域具有唯一的名称,然后重试。
  • amountAboveLimit 这超过了 <device(s)> 能够支持的内容。
  • appLaunchFailed 抱歉,未能在 <device(s)> 上启动“<app name>”。
  • armFailure 无法开启 <device(s)>。
  • armLevelNeeded 我不确定要将 <device(s)> 设置为哪个级别。试着说“将<device(s)>设为<低安全性>”或“将<device(s)>设为<高安全性>”
  • authFailure 我似乎无法访问 <device(s)>。请尝试检查该应用,确保您的 <device/devices> 已完全设置妥当。
  • bagFull <device(s)> <has/have> <a full bag/full bags>。请先清空 <it/them>并重试。
  • belowMinimumLightEffectsDuration 少于 5 分钟的最短持续时间。请重试。
  • belowMinimumTimerDuration 我无法设置 <device(s)> 的时间太短。请重试。
  • binFull <device(s)> <has/have> <a full bin/full bins>。
  • cancelArmingRestricted 抱歉,我无法取消开启 <device(s)> 的报警器。
  • cancelTooLate 抱歉,已无法取消。请改用 <device(s)> 或应用。
  • channelSwitchFailed 抱歉,未能切换到 <channel name>频道。请稍后重试。
  • chargerIssue 抱歉,看起来像是 <device(s)> <has/have> <acharger issue/charger issues>。
  • CommandInsertFailed 无法处理对 <device(s)> 的命令。
  • deadBattery <device(s)> <has/have> <a 已耗尽电池/已耗尽的电池>。
  • degreesOutOfRange 请求的角度超出 <device(s)> 的范围。
  • deviceAlertNeedsAssistance <device(s)> <有>一条有效提醒和 <need(s)>您的帮助。
  • deviceAtExtremeTemperature <device(s)> <is/are> 处于 <极端温度/极端温度>。
  • deviceBusy 抱歉,<device(s)>目前正在执行一些操作。
  • deviceCharging 抱歉,<device(s)> 似乎无法执行此操作,因为 (ha_shared.Itsthemre size=$item.devices.total_device_count) 正在充电。
  • deviceClogged 抱歉,<device(s)> 似乎已阻塞。
  • deviceCurrentlyDispensing <device(s)> 正在分配食物。
  • deviceDoorOpen <device(s)> 上的门开着。请将其关好,然后重试。
  • deviceHandleClosed 手柄已在 <device(s)> 上关闭。请打开它,然后重试。
  • deviceJammingDetected <device(s)> <is/are> 卡住。
  • deviceLidOpen 在 <device(s)> 上,盖子已打开。请先关上盖子,然后重试。
  • deviceNeedsRepair : 需要维修的 <device(s)> <need(s)>。请与您当地的服务经销商联系。
  • deviceNotDocked 抱歉,<device(s)> 似乎<isn't/aren't>已插入基座。请停靠 <it/them>,然后重试。
  • deviceNotFound <device(s)> <is/are>不可用。 您可能需要尝试重新设置 <it/them>。
  • deviceNotMounted 抱歉,<device(s)> 似乎无法执行此操作,因为 <it/they> <is/are>未装载。
  • deviceNotReady <device(s)> <is/are>未准备就绪。
  • deviceStuck <device(s)> <is/are>卡住,需要您帮助。
  • deviceTampered <device(s)> <已>被篡改。
  • 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 <device(s)> <is/are>处于紧急供暖模式,因此 <it/they> 必须手动进行调整。
  • faultyBattery <device(s)> <has/have> <a faulty battery/faulty bateries>。
  • floorUnreachable <device(s)> 无法进入该房间。请将 <it/them>移到正确的楼层,然后重试。
  • functionNotSupported 实际上,<device(s)> <不/不>支持该功能。
  • genDispenseNotSupported 我需要知道您想分发什么内容。请输入内容的名称重试。
  • hardError 抱歉,出了点问题,我没法控制你的家居设备。
  • hardError 抱歉,出了点问题,我没法控制你的家居设备。
  • inAutoMode <device(s)> <is/are> 当前设为自动模式。若要调节温度,你需要把<it/them>切换到其他模式。
  • inAwayMode <device(s)> <is/are> 当前设置为外出模式。若想控制温控器,您需要使用手机、平板电脑或计算机上的 Nest 应用将其手动切换到在家模式。
  • inDryMode <device(s)> <is/are>当前设置为除湿模式。若要调节温度,你需要把<it/them>切换到其他模式。
  • inEcoMode <device(s)> <is/are>当前设为节能模式。若要调节温度,你需要把<it/them>切换到其他模式。
  • inFanOnlyMode <device(s)> <is/are> 当前设为风扇模式。若要调节温度,你需要把<it/them>切换到其他模式。
  • inHeatOrCool <device(s)> <is/are>未处于供暖/制冷模式。
  • inHumidifierMode <device(s)> <is/are>当前已设为加湿模式。若要调节温度,你需要把<it/them>切换到其他模式。
  • inOffMode <device(s)> <is/are>目前处于关闭状态。若要调节温度,您需将 <it/them> 切换至其他模式。
  • inPurifierMode <device(s)> <is/are>当前设为净化模式。若要调节温度,你需要把<it/them>切换到其他模式。
  • inSleepMode <device(s)> <is/are>处于睡眠模式。请稍后重试。
  • inSoftwareUpdate <device(s)> <is/are>目前正在进行软件更新。
  • lockFailure 无法锁定 <device(s)>。
  • lockState <device(s)> <is/are>当前处于锁定状态。
  • lockToRange 该温度不在 <device(s)> 锁定的范围内。
  • lowBattery <device(s)> <有>电量不足。
  • maxSettingReached <device(s)> <is/are> 已设为最高设置。
  • maxSpeedReached <device(s)> <is/are>已设置为最大速度。
  • minSettingReached <device(s)> <is/are> 已设置为最低设置。
  • minSpeedReached <device(s)> <is/are> 已设置为最低速度。
  • monitoringServiceConnectionLost <device(s)> <has/have> 丢失了与监控服务的 <its/their>连接。
  • needAttachment 抱歉,<device(s)> 似乎缺少必要的附件。请更换它,然后重试。
  • needBin 抱歉,<device(s)> 似乎缺少分箱。请更换它,然后重试。
  • needPads <device(s)> <need(s)> new pads.
  • needSoftwareUpdate : <device(s)> <need(s)> 次软件更新。
  • needWater <device(s)> <need(s)> water.
  • networkProfileNotRecognized 抱歉,我在 <device(s)> 上无法识别“<network profile>”。
  • networkSpeedTestInProgress 我已经在测试 <network> <speed/speeds>>。
  • noAvailableApp 抱歉,<app name> 似乎不可用。
  • noAvailableChannel 抱歉,<channel name> 似乎无法访问频道。
  • noChannelSubscription 抱歉,您目前未订阅<频道名称>频道。
  • noTimerExists 抱歉,<device(s)> 上似乎未设置任何计时器。
  • notSupported 抱歉,<device(s)>不支持该模式。
  • obstructionDetected <device(s)> 检测到障碍物。
  • 离线、device 离线 抱歉,<device(s)>目前似乎不可用。
  • onRequiresMode 请指定要开启的模式。
  • Password Password 抱歉,该 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 - 当儿童安全模式处于启用状态时,<device(s)> 会禁止执行该操作。
  • roomOnDifferentFloors <device(s)> 无法访问这些会议室,因为它们位于不同的楼层。
  • safetyShutOff <device(s)> <is/are>处于安全断电模式,因此 <it/them> 必须手动进行调整。
  • sceneCannotBeApply 抱歉,<device(s)> 无法应用。
  • securityRestriction <device(s)> <具有>安全限制。
  • SoftwareUpdateNotAvailable 抱歉,<device(s)> 上没有可用的软件更新。
  • startRequiresTime 为此,您需要告诉我您想运行 <device(s)> 多长时间。
  • tillCoolingDown <device(s)> <is/are>仍在冷却。
  • tillWarmingUp <device(s)> <is/are>仍在预热。
  • streamAvailable 抱歉,目前似乎无法从 <device(s)>上进行流式传输。
  • streamUnplayable 抱歉,我目前无法通过 <device(s)> 播放视频流。
  • tankEmpty <device(s)> <has/have> <空罐/空罐>。请先将 <it/them>加满,然后重试。
  • targetAlreadyReached 抱歉,当前的温度似乎已调。
  • timeValueOutOfRange 无法为这一时长设置 <device(s)>。
  • Too manyFailedFaileds 抱歉,尝试的失败次数过多。请前往设备的应用中完成这项操作。
  • transientError 抱歉,控制 <device(s)>时出了点问题。请重试。
  • 关闭、deviceTurnedOff <device(s)> 立即关闭。
  • FailedToLocateDevice 找不到 <device(s)>。
  • UnknownFoodPreset <device(s)> 不支持该食物预设。
  • unlockFailure 无法解锁 <device(s)>。
  • unpausableState 目前无法暂停 <device(s)>。
  • userCancelled 确定
  • valueOutOfRange <device(s)> 无法设为该温度。

异常

当存在与命令相关的问题或提醒时,您应返回异常。该命令可能会成功,也可能失败。

如果命令成功 (status = "SUCCESS"),请使用 StatusReport 特征(针对目标设备以外的设备)或返回适当的 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>。请先清空 <it/them>并重试。
  • binFull <device(s)> <has/have> <a full bin/full bins>。
  • carMonoxideDetected 在 <house name>中检测到一氧化碳。
  • deviceAtExtremeTemperature <device(s)> <is/are> 处于 <极端温度/极端温度>。
  • deviceJammingDetected <device(s)> <is/are> 卡住。
  • deviceMoved <device(s)> <was/were>移动。
  • deviceOpen <device(s)> <is/are> open。
  • deviceTampered <device(s)> <已>被篡改。
  • deviceUnplugged <device(s)> <is/are>未插电。
  • floorUnreachable <device(s)> 无法进入该房间。请将 <it/them>移到正确的楼层,然后重试。
  • hardwareFailure <device(s)> <有>硬件问题。
  • inSoftwareUpdate <device(s)> <is/are>目前正在进行软件更新。
  • isBypassed 目前已绕过<device(s)> <is/are>。
  • lowBattery <device(s)> <有>电量不足。
  • motionDetected <device(s)> <detect(s)> 动作。
  • needPads <device(s)> <need(s)> new pads.
  • needSoftwareUpdate : <device(s)> <need(s)> 次软件更新。
  • needWater <device(s)> <need(s)> water.
  • networkJammingDetected 与 <device(s)> 的家庭网络连接无法正常工作。
  • noIssuesReported <device(s)> 未报告任何问题。
  • roomOnDifferentFloors <device(s)> 无法访问这些会议室,因为它们位于不同的楼层。
  • runCycleFinished <device(s)> <has/have>完成运行。
  • securityRestriction <device(s)> <具有>安全限制。
  • smokeDetected 在 <house name>中检测到烟雾。
  • tankEmpty <device(s)> <has/have> <空罐/空罐>。请先将 <it/them>加满,然后重试。
  • usingCellularBackup <device(s)> <is/are>正在使用移动网络备份。
  • waterLeakDetected <device(s)> <detect(s)> 有漏水。