欢迎使用 Google Home 开发者中心,这是一个学习如何开发智能家居 Action 的新平台。注意:构建 Action 的工作仍需在 Actions 控制台中完成。

错误和异常

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

错误数

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

错误代码可以在设备级别或全局级别添加。例如,如果用户有一个来自同一个提供商的许多灯,并且由 hub 控制,则当用户要求关闭所有灯时,该提供商可能会在单个灯处于离线状态时返回设备级错误,或者在整个 hub 处于离线状态且无法控制灯时返回全局级错误。如果所有设备处于离线状态,则使用全局级错误或设备级错误没有任何区别。如果设备处于离线状态,您应该返回 reportState 报告 {"online": false} 状态,即使返回 deviceOffline 错误代码也是如此。

步骤简述:

  • 全局级错误:响应中的所有设备均具有相同的错误
  • 本地级错误:混合响应,包含错误和成功情况

全局级错误

以下 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 小时。请重试。
  • AboveMaximum 计时器时长 我只能设置 <device>(s),最多只能设置 <时间段>
  • actionNotAvailable 抱歉,我目前好像没法这样做。
  • actionUnavailableWhenRunning <device(s)> <is/are> 正在运行,因此我无法进行任何更改。
  • 已经启动 <设备>> <is/are> 已经开启。
  • atAtMax <device(s)> <is/are> 已设为最高温度。
  • alreadyAtMin <device(s)> <is/are> 已设为最低温度。
  • 已关闭 <device(s)> <is/are> 已关闭。
  • 已关闭报警器 <device(s)> <is/are> 已关闭报警器。
  • 已插入基座 <设备>> <is/are> 已插入基座。
  • hasInState <device(s)> <is/are> already in that state.
  • 已锁定 <device(s)> <is/are> 已锁定。
  • 已关闭 <device(s)> <is/are> 已关闭。
  • 已开启 <device(s)> <is/are> 已经开启。
  • 已打开 <设备>> <is/are> 已打开。
  • 已暂停 <设备>> <is/are> 已暂停。
  • 已开始 <device(s)> <is/are> 已经开始。
  • 已停止 <device(s)> <is/are> 已停止。
  • 已解锁 <device(s)> <is/are> 已经解锁。
  • ambiguousZoneName 抱歉,<device>(s)> 无法识别您的可用区。请确保各个区域都有唯一的名称,然后再试一次。
  • amountAboveLimit 这超过了 <device(s)> 可以支持的数量。
  • appLaunchFailed 抱歉,未能在“<device>(s)>”上启动“<app name>”。
  • armFailure <device(s)> 无法开启。
  • armLevelNeeded 我不确定将 <device>(s) 设为哪个级别。试着说“将 <设备> 设为<低安全性>”或“将 <设备>> 设为 <高安全性>”
  • authFailure 我似乎无法访问 <device(s)>。请尝试检查该应用,确保您的 <device/devices> 已完全设置。
  • bagFull <device(s)> <has/have> <a full bag/full bags>。请先清空 <it/them>,然后重试。
  • UnderMinimumLightEffectsDuration 这小于 5 分钟的最短时长。请重试。
  • minimumMinimum 计时器 Duration 我无法设置这么短的<设备>。请重试。
  • binFull <device(s)> <has/have> <a full/bin/bins>
  • CancelArmingRestricted 抱歉,我无法取消开启 <device >(s)> 的选项。
  • CancelTooLate 抱歉, 现在没法取消了。请改用 <device(s)> 或此应用。
  • channelSwitchFailed 非常抱歉,未能切换到“<频道名称>”频道。请稍后重试。
  • 充电器问题 抱歉,系统好像为 <device(s)> <has/have> <a 充电器问题/充电器问题>
  • CommandInsertFailed 无法处理 <device>(s)> 的命令。
  • DeBattery <device(s)> <has/have> < 已耗尽的电池/已耗尽的电池>。
  • LatitudeOutOfRange 请求的度数超出了 <device>(s)> 的范围。
  • deviceAlertNeedsAssistance <device(s)> <has/has> 活跃警报和 <need(s)> your help.
  • deviceAtExtremeTemperature <device>(s) <is/are> at <an exterretemporate/extrememates.
  • deviceBusy 抱歉,<device(s)> 似乎正在执行某种操作。
  • deviceCharging 抱歉,<device(s)> 似乎无法执行这项操作,因为 (ha_shared.ItsThatre size=$item.devices.total_device_count) 正在充电。
  • deviceClogged 抱歉,<device(s)> 好像是卡住了。
  • deviceCurrentlyDispensing <device(s)> 目前正在进行分配。
  • deviceDoorOpen 门在 <device>上打开。请关好它并重试。
  • deviceHandleClosed 此标识名在 <device(s)> 上已关闭。请打开它并重试。
  • deviceJammingDetected <device(s)> <is/are> jams.
  • deviceLidOpen 盖子在 <device(s)>上打开。请关上盖子,然后重试。
  • deviceNeedsRepair : <device(s)> <need(s)> 需要修复。请联系你的当地服务经销商。
  • deviceNotDocked 抱歉,<device>(s) 好像不对接。请插入基座以重试。
  • deviceNotFound <device(s)> <is/are> 不可用。您可能需要尝试重新设置 <it/them>。
  • deviceNotMounted 抱歉,<device>(s) 似乎无法执行这项操作,因为 <it/people> <is/are> 并未装载。
  • deviceNotReady <device(s)> <is/are>尚未准备就绪。
  • deviceStuck <device(s)> <is/are> 卡住,需要您寻求帮助。
  • deviceTampered <device/(s)> <has/has> 被篡改。
  • deviceThermalShutdown 抱歉,<device(s)> 似乎因极端温度关闭了。
  • directResponseOnlyUnreachable <设备> <不/不支持> 遥控器。
  • 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)> 的门已经开着有一段时间了。请打开门并确保里面不是空的,然后再试一次。
  • 紧急呼叫开启 <设备>(is)
  • faultyBattery <device(s)> <has/have> <a ult 电池/电池故障>。
  • floorUnreachable <device(s)> 无法到达该房间。请将 <it/them> 移到右侧楼层,然后重试。
  • 函数 NotSupported 实际上,<device(s)> <不/不支持 该功能。
  • generalDispenseNotSupported 我需要知道您要分配的内容。请使用商品名称重试。
  • 硬错误 抱歉,出了点问题,我没法控制你的家居设备。
  • 硬错误 抱歉,出了点问题,我没法控制你的家居设备。
  • 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)> 无法锁定。
  • 锁定状态 <设备>> <is/are> 目前锁定。
  • LockToRange 该温度超出了 <device>(s)> 的锁定范围。
  • LowBattery <device(s)> <has/have> 低电量。
  • 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> 到监控服务的 <it/s> 连接。
  • needAttachment 抱歉,<device(s)> <is/are>缺少必要的附件。请先更换它,然后重试。
  • needBin 抱歉,<device/(s)> <is/are> 似乎缺少箱。请先更换它,然后重试。
  • needPads <device(s)> <need(s)> 新垫。
  • needSoftwareUpdate <device(s)> <need(s)> 软件更新。
  • needWater <device(s)> <need(s)> 水。
  • networkProfileNotRecognized 抱歉,我无法识别 <device>(s)> 上的“<network profile>”。
  • networkSpeedTestInProgress 我已经在测试 <network> <speed/speeds>>。
  • noAvailableApp 抱歉,<app name> 似乎无法使用。
  • noAvailableChannel 抱歉,频道“<channel name>”似乎无法使用。
  • noChannelSubscription 抱歉,您目前没有订阅“<频道名称>”。
  • no 依据计时器 抱歉,在 <device(s)> 上似乎未设置任何计时器。
  • 不支持 : 抱歉,<device class(s)> 不支持该模式。
  • obstructionDetected <device(s)> 检测到障碍物。
  • 离线 ,设备离线 抱歉,<device>(s) 好像无法使用。
  • onRequiresMode 请指定要开启的模式。
  • passwordsInvalid 抱歉,PIN 码似乎不正确。
  • percentOutOfRange 抱歉,无法将 <device >(s)> 设为 <percent>。
  • pin 使用量错误 (passphrase 使用量)
  • rainDetectdetect 我未打开 <device(s)>,因为检测到下雨了。
  • rangeTooClose 对于 <device>(s) 而言,温度范围太短,无法进行温控。请选择相距更远的温度。
  • relinkRequired 抱歉,您的帐号似乎出了点问题。请使用 Google Home 或 Google 助理应用重新关联 <device>(s)
  • remoteSetDisabled
    • 可选参数 errorCodeReason
    • currentlyArmed - 抱歉,由于安保等级已开启,因此您需要使用 <设备>或该应用进行任何更改。
    • remoteUnlockNotAllowed - 抱歉,我没法远程解锁<device>。
    • remoteControlOff - 该操作目前已停用。请在 <设备>上启用远程控制,然后重试。
    • childSafetyModeActive - 当儿童安全模式处于启用状态时,系统会为 <device(s)> 停用该操作。
  • roomOnDifferenceFloors <device(s)> 无法到达这些房间,因为它们位于不同楼层。
  • safetyShutOff(安全关闭) <device/(s)> <is/are> 处于安全关机模式,因此 <it/her> 必须手动调整。
  • sceneCannotBeApplied 抱歉,无法应用 <device(s)>。
  • securityRestriction <device(s)> <has/have> 安全限制。
  • SoftwareUpdateNotAvailable 抱歉,<device >(s)> 上没有任何软件更新。
  • startRequiresTime 为此,您需要告诉我您想要运行<device>(s)>多长时间。
  • tillCoolingDown <device(s)> <is/are>冷却。
  • tillWarmingUp : <device(s)> <is/are>仍在升温。
  • 视频流不可用 抱歉,目前似乎无法通过 <device(s)> 获取视频流。
  • streamUnplayable 抱歉,我目前没法播放来自<device>的视频流。
  • tankEmpty <device(s)> <has/have> <an empty tank/empty tanks>. Please fill <it/them> and try again.
  • targetAlreadyReached 抱歉,温度似乎已经达到上限。
  • timeValueOutOfRange <device(s)> 无法设置该时长。
  • Too ManyFailedFailures 抱歉,失败的尝试次数过多。请转到设备的应用中完成这项操作。
  • transientError 抱歉,控制<device>(s)>时出了点问题。请重试。
  • turnOff , deviceTurnedOff : <device(s)> <is/are> 目前已关闭。
  • cannotToLocateDevice 我找不到 <device >(s)>。
  • UnknownFoodPreset <device(s)> 不支持该食物预设。
  • unlockFailure <device(s)> 无法解锁。
  • unpausableState <device(s)> 目前无法暂停。
  • userCancelled ok
  • valueOutOfRange <device(s)> 无法设为该温度。

例外情况

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

如果命令成功(状态 =“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/bins>
  • carbonMonoxideDetected 在 <house name> 中检测到一氧化碳。
  • deviceAtExtremeTemperature <device>(s) <is/are> at <an exterretemporate/extrememates.
  • deviceJammingDetected <device(s)> <is/are> jams.
  • deviceMoved <device(s)> <was/were> 已移动。
  • deviceOpen <device(s)> <is/are> 打开。
  • deviceTampered <device/(s)> <has/has> 被篡改。
  • deviceUnplugged <device(s)> <is/are> 已拔下。
  • floorUnreachable <device(s)> 无法到达该房间。请将 <it/them> 移到右侧楼层,然后重试。
  • hardwareFailure <device(s)> <has/have> 硬件问题。
  • inSoftwareUpdate <device>(s)> <is/are> 目前正在进行软件更新。
  • isBypassed <device(s)> <is/are> 目前绕过。
  • LowBattery <device(s)> <has/have> 低电量。
  • MotionDetected <device(s)> <detect(s)> motion。
  • needPads <device(s)> <need(s)> 新垫。
  • needSoftwareUpdate <device(s)> <need(s)> 软件更新。
  • needWater <device(s)> <need(s)> 水。
  • networkJammingDetected 与 <device(s)> 的家庭网络连接无法正常工作。
  • noIssuesReported <device(s)> 未报告任何问题。
  • roomOnDifferenceFloors <device(s)> 无法到达这些房间,因为它们位于不同楼层。
  • runCycleFinished <device(s)> <has/have> 已完成运行。
  • securityRestriction <device(s)> <has/have> 安全限制。
  • smokeDetected 在 <house name>中检测到烟雾。
  • tankEmpty <device(s)> <has/have> <an empty tank/empty tanks>. Please fill <it/them> and try again.
  • useCellularBackup 使用移动网络备份的 <device/(s)> <is/are>。
  • waterLeakDetected <device(s)> <detect(s)> 漏水。