欢迎使用 Google Home 开发者中心,您可以在这里学习有关如何开发智能家居 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 小时的最长时长。请重试。
  • AboveMaximumTimeoutDuration 我只能设置 <device(s)>,最长不超过 <time time>
  • actionNotAvailable 抱歉,我现在好像无法这样做。
  • actionUnavailable 娜 Running <device(s)> <is/are> 目前正在运行,所以我不能进行任何更改。
  • 已启用 Armed : <device(s)> <is/are> 已开启。
  • atAtMax <device(s)> <is/are> 已经设为最高温度。
  • atAtMin : <device(s)> <is/are> 已设为最低温度。
  • 已关闭 <device(s)> <is/are> has already close.
  • 已关闭警报 : <device(s)> <is/are> 已关闭警报。
  • 已插入基座 <device(s)> <is/are> 已插入基座。
  • alreadyInState <device(s)> <is/are> 已处于该状态。
  • 已锁定 : <device(s)> <is/are> 已锁定。
  • 已开启 <device(s)> <is/are> 已关闭。
  • 已开启 <device(s)> <is/are> 已开启。
  • 已打开 <device(s)> <is/are>已开启。
  • AlreadyPaused <device(s)> <is/are> already paused.
  • 已经开始 <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)> 设置为哪个级别。试着说“将 <设备(s)> 设为<低安全性>”或“将 <设备(s)> 设置为<高安全性>”
  • authFailure 我似乎无法访问 <device(s)>。请尝试检查应用,确保您的 <device/devices> 已完全设置。
  • bagFull <device(s)> <has/has> <a full bag/full bags>. please empty <it/them> and try again.
  • minimumMinimumLightEffectsDuration 这少于 5 分钟的最短时长。请重试。
  • minimumMinimum 计时器时长 我无法设置这么短的时间<device(s)>。请重试。
  • binFull <device(s)> <has/has> <a full bin/full bins>.
  • cancelArmingRestricted 抱歉,我无法取消开启<device(s)>。
  • CancelTooLate 抱歉,为时已晚,无法取消。请改用 <device(s)> 或应用。
  • channelSwitchFailed 抱歉,未能切换到 <channel name>。请稍后再试。
  • 充电器问题 抱歉,好像有 <device(s)> <has/has> <a 充电器问题/充电器问题>
  • CommandInsertFailed 无法处理 <device(s)> 的命令。
  • DeadBattery <device(s)> <has/has> <dadBattery/dad Batterys>。
  • degreesOutOfRange : 请求的角度超出 <device(s)> 的范围。
  • DeviceAlertNeedsAssistance <device(s)> <has/has> 已启用的警报和 <need(s)> 您的帮助。
  • deviceAtExtremeTemperature <设备
  • deviceBusy 抱歉,<device(s)> 似乎已在执行某些操作。
  • deviceCharging 抱歉,<device(s)> 似乎无法执行这项操作,因为 (ha_shared.ItsItre size=$item.devices.total_device_count) 正在充电。
  • deviceClogged 抱歉,<device(s)> 似乎是卡住的。
  • deviceCurrentlyDispensing <device(s)> 目前正在进行分配。
  • deviceDoorOpen 门在 <device>上打开。请关好门,然后重试。
  • deviceHandleClosed 手柄已在 <device(s)> 上关闭。请打开它并重试。
  • deviceJammingDetected <device(s)> <is/are> 卡住。
  • deviceLidOpen 盖子在 <device(s)> 上打开。请关上盖子,然后重试。
  • deviceNeedsRepair :待修复的 <device(s)> <need(s)>。请联系你的当地服务经销商。
  • deviceNotDocked 抱歉,似乎 <device(s)> <isn't/arentt> 已插入基座。请将 <it/them> 停靠,然后重试。
  • deviceNotFound <device(s)> <is/are> 不可用。您可能需要重新设置 <it/them>。
  • deviceNotMounted 抱歉,<device(s)> 似乎无法执行该操作,因为 <it/它们> <is/are>未装载。
  • deviceNotReady <device(s)> <is/are>n.ready。
  • 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/它们>。
  • faultyBattery <device(s)> <has/has> <a ult 电池/电池故障>。
  • floorUnreachable <device(s)> 无法进入该房间。请将 <it/them> 移到正确的楼层,然后重试。
  • functionNotSupported : 实际上,<device(s)> <不/不{2}支持该功能。
  • 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>n’t in hot/cool mode.
  • 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)> 无法锁定。
  • 锁定状态 <设备(s)> <is/are> 目前锁定。
  • LockToRange 该温度不在 <device(s)> 的锁定范围内。
  • lowBattery <device(s)> <has/has> 电池电量低。
  • maxSettingReached <device(s)> <is/are> 已设置为最高设置。
  • maxSpeedReached <device(s)> <is/are> 已设置为最大速度。
  • minSettingReached <device(s)> <is/are> 已设置为最低设置。
  • minSpeedReached <device(s)> <is/are> 已设置为最小速度。
  • monitoringServiceConnectionLost <device(s)> <has/has> 与监控服务断开了 <it/her> 连接。
  • need 附件 抱歉,<device(s)> <is/are> 缺少必需的附件。请先更换它,然后重试。
  • needBin 抱歉,似乎 <device(s)> <is/are> 缺少箱。请先更换它,然后重试。
  • needPads <device(s)> <need(s)> new pad。
  • 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 抱歉,您目前没有订阅<channel name>。
  • noTimingExists 抱歉,似乎 <device(s)> 上没有设置任何计时器。
  • 不支持 抱歉,<device(s)> 无法使用该模式。
  • obstructionDetected <device(s)> 检测到障碍物。
  • 离线 ,设备离线 抱歉,目前似乎无法使用 <device(s)> <is/are>。
  • onRequiresMode 请指定要开启的模式。
  • passwordsIncorrect 抱歉,PIN 码似乎不正确。
  • percentageOutOfRange 抱歉,无法将 <device(s)> 设置为 <percent>。
  • PIN 不正确 (passphraseIncorrect)
  • rainDetected 我没有打开 <device(s)>,因为系统检测到雨。
  • rangeTooClose 对于 <device(s)> 来说,这些温度过高并无法实现适温范围。请选择相距较远的温度。
  • relinkRequired 抱歉,您的帐号似乎出现问题。请使用 Google Home 或 Google 助理应用重新关联 <设备>。
  • remoteSetDisabled
    • 可选参数 errorCodeReason
    • currentlyArmed - 抱歉,由于安防系统已开启,您需要使用 <设备>或应用进行更改。
    • remoteUnlockNotAllowed - 抱歉,我没法远程解锁<device>。
    • remoteControlOff - 该操作目前处于停用状态。请在 <device(s)> 上启用遥控器,然后重试。
    • childSafetyModeActive - 当儿童安全模式处于活动状态时,<device(s)> 会停用该操作。
  • roomOnDifferenceFloors <device(s)> 无法访问这些房间,因为它们位于不同的楼层。
  • safetyShutOff <device(s)> <is/are> 处于安全关机模式,因此<it/它们>必须手动调整。
  • sceneCannotBeApply 抱歉,无法应用 <device(s)>。
  • securityRestriction <device(s)> <has/has> 安全限制。
  • SoftwareUpdateNotAvailable 抱歉,<device(s)> 上没有软件更新。
  • startRequiresTime 为此,您需要告诉我您想要运行 <device(s)> 多长时间。
  • tillCoolingDown <device(s)> <is/are> 仍在冷却。
  • tillWarmingUp <device(s)> <is/are> 仍在预热。
  • streamUnavailable 抱歉,目前好像无法通过 <device(s)> 获取数据流。
  • streamUnplayable 抱歉,我目前无法播放来自 <device(s)> 的视频流。
  • tankEmpty <device(s)> <has/has> <an empty 坦克/空水箱>。请填写 <it/them> 并重试。
  • targetAlreadyReached 抱歉,这似乎是当前温度。
  • timeValueOutOfRange :无法在 该时间段内设置 <device(s)>。
  • tooManyFailedFaileds 抱歉,尝试失败的次数过多。请转到设备的应用中完成这项操作。
  • transientError 抱歉,控制 <device(s)> 时出错。请重试。
  • turnOff , deviceTurnedOff <device(s)> <is/are> 现已关闭。
  • unableToLocateDevice 我找不到 <device(s)>
  • unFoodPreset <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/has> <a full bag/full bags>. please empty <it/them> and try again.
  • binFull <device(s)> <has/has> <a full bin/full bins>.
  • carbonMonoxideDetected 在 <house name>中检测到一氧化碳。
  • deviceAtExtremeTemperature <设备
  • 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)> <has/has> 硬件问题。
  • inSoftwareUpdate <device(s)> <is/are> 目前正在进行软件更新。
  • isBypassed <device(s)> <is/are> 目前绕过。
  • lowBattery <device(s)> <has/has> 电池电量低。
  • motionDetected <device(s)> <detect(s)> motion。
  • needPads <device(s)> <need(s)> new pad。
  • needSoftwareUpdate <device(s)> <need(s)> 软件更新。
  • needWater <device(s)> <need(s)> water.
  • networkJammingDetected 到 <device(s)> 的家庭网络连接无法正常工作。
  • noIssuesReported <device(s)> 未报告任何问题。
  • roomOnDifferenceFloors <device(s)> 无法访问这些房间,因为它们位于不同的楼层。
  • runCycleFinished <device(s)> <has/has> finished running.
  • securityRestriction <device(s)> <has/has> 安全限制。
  • smokeDetected 在 <house name>中检测到烟雾。
  • tankEmpty <device(s)> <has/has> <an empty 坦克/空水箱>。请填写 <it/them> 并重试。
  • UsingCellularBackup <device(s)> <is/are> 使用移动网络备份。
  • waterLeakDetected <device(s)> <detect(s)> 漏水。