Google 致力于为黑人社区推动种族平等。查看具体举措

错误消息

错误条件是开发周期的一部分,可能从简单的故障(如参数无效或缺失)到更复杂的场景(例如意外的状态,甚至是与设备相关的设置),而必须在 API 之外解决。

在 API 调用期间发生错误时,系统将发送以下格式的响应:

{
  "error": "Temperature '$temp' is in wrong format",
  "type": "https://developers.nest.com/documentation/cloud/error-messages#format-error",
  "message": "Temperature '$temp' is in wrong format",
  "instance": "31441a94-ed26-11e4-90ec-1681e6b88ec1",
  "details": {
    "field_name": "$temp"
  }
}

所有错误消息都包含 errortypemessageinstance 字段。details 对象是可选的。

字段 说明
error 简短的错误消息格式。
type 提供关于错误情况详细信息的页面(本页)。
message 长变量格式,可能会使用变量提供更多详细信息。当变量包含在消息中时,它将显示在 details 对象中。
instance 包含每个调用独有的错误标识符的文本字符串。如果您报告服务存在问题,我们可能会要求您提供实例编号。
details 可选。包含插入到 message 中的变量。消息可以包含多个变量。

如需了解与 Nest API 无关的错误,请参阅其他错误代码和消息

已屏蔽

已超出速率限制

参数
HTTP 状态代码:429 请求过多
error已屏蔽
typehttps://developers.nest.com/reference/error-messages#blocked
message已屏蔽

烟雾/安防系统关闭期间无法启动风扇

已启用紧急关闭。在正常操作恢复之前,不接受 API 调用。

参数
HTTP 状态代码:400 请求错误
error烟雾/安防系统关闭期间无法启动风扇
typehttps://developers.nest.com/reference/error-messages#safety-shutoff-on
message烟雾/安防系统关闭期间无法启动风扇

当应急热源开启时,无法更改“外出”状态

产品尝试在紧急制热处于开启状态时更改“外出”状态。

参数
HTTP 状态代码:400 请求错误
error当应急热源开启时,无法更改“外出”状态
typehttps://developers.nest.com/reference/error-messages#emergency-heat-is-on
message当应急热源开启时,无法更改“外出”状态

在节能事件期间无法更改 HVAC 模式

由 Nest 能源合作伙伴定义的节能事件已生效。API 调用会被拒绝,直到节能事件结束。

参数
HTTP 状态代码:400 请求错误
error在节能事件期间无法更改 HVAC 模式
typehttps://developers.nest.com/reference/error-messages#energy-saving-event-on
message在节能事件期间无法更改 HVAC 模式

无法更改 HVAC 模式

模式与请求不兼容。

例如,在以下情况下,您可能会收到此消息:

  • 温控器的 HVAC 系统不支持您的产品请求的模式:heatcoolheat-cooleco
  • HVAC 模式已设置为 eco,产品会尝试设置 target_temperature
参数
HTTP 状态代码:400 请求错误
error无法将 HVAC 模式更改为 $mode;HVAC 无法$action
typehttps://developers.nest.com/reference/error-messages#incompatible-mode
message无法将 HVAC 模式更改为 $mode;HVAC 无法$action
details$mode
$action

当恒温器锁定处于启用状态时,无法更改 HVAC 模式

用户必须解锁恒温器才能为产品写入数据。

参数
HTTP 状态代码:400 请求错误
error当恒温器锁定处于启用状态时,无法更改 HVAC 模式
typehttps://developers.nest.com/reference/error-messages#lock-enabled
message当恒温器锁定处于启用状态时,无法更改 HVAC 模式

无法同时设置 C 和 F 温度

该产品尝试同时设置摄氏度和目标温度。产品应仅设置 temperature_scale (C/F) 指定的目标温度。

参数
HTTP 状态代码:400 请求错误
error无法同时设置 C 和 F 温度
typehttps://developers.nest.com/reference/error-messages#multiple-value-changes
message无法同时设置 C 和 F 温度

由于模式不兼容,无法设置 fan_timer_active 开启/关闭

HVAC 系统风扇已启动(由用户手动设置、按时间表启动,或因 HVAC 供暖/制冷周期而启动)。

如果您没有获得预期结果,则很可能是设备具有无法通过 API 替换的内置行为。

参数
HTTP 状态代码:400 请求错误
error由于模式“$mode”不兼容,无法设置 fan_timer_active 的开启/关闭
typehttps://developers.nest.com/reference/error-messages#incompatible-fan-mode
message由于模式“$mode”不兼容,无法设置 fan_timer_active 的开启/关闭
details$mode

无法将 fan_timer_duration 设置为所选值

产品尝试将 fan_timer_duration 设置为无效值。如需查看有效值列表,请参阅 fan_timer_duration

参数
HTTP 状态代码:400 请求错误
error无法将 fan_timer_duration 设置为所选值。如需了解允许的值,请参阅 API 参考文档。
typehttps://developers.nest.com/reference/error-messages#invalid-fan-timer-duration
message无法将 fan_timer_duration 设置为所选值。如需了解允许的值,请参阅 API 参考文档。

目标温度不能设为高于目标最高温度

恒温器处于 heat-cool 模式,并且产品尝试设置的目标温度低于/高于这个范围。例如,产品尝试在 target_temperature_high_c 为 24°C 时将 target_temperature_low_c 设置为 25°C。

参数
HTTP 状态代码:400 请求错误
error无法将目标最低温度 $lowTemp 设置为高于目标最高温度 $highTemp
typehttps://developers.nest.com/reference/error-messages#low-high-error
message无法将目标最低温度 $lowTemp 设置为高于目标最高温度 $highTemp
details$lowTemp
$highTemp

目标温度不得接近 N 摄氏度/F

产品尝试设置的目标温度值过于接近目标高温/低温(例如 target_temperature_high_f)。

参数
HTTP 状态代码:400 请求错误
error目标温度不得接近 N 摄氏度/F
typehttps://developers.nest.com/reference/error-messages#range-error
message无法将目标温度设为接近 $min 度($scale
details$min
$scale

当模式为 $mode 时,无法设置 target_temperature

恒温器或结构当前处于不支持 API 请求的模式。

例如,当 HVAC 系统为 off 或处于 heat-cool 模式时,您无法设置 target_temperature_ftarget_temperature_c。在恒温器/结构切换回非受限模式之前,此值无法更改。

在此消息中,$fieldName 可以是任何目标温度值,$mode 可以是以下任何值:ecoemer_heat_enableheat-coolheatcooloffhvac_safety_shutoff_active

参数
HTTP 状态代码:400 请求错误
error当模式为 $mode 时,无法设置 target_temperature
typehttps://developers.nest.com/reference/error-messages#mode-error
message当模式为 $mode 时,无法设置 $fieldName
details$fieldName
$mode

必须先更新设备固件,然后才能更改 HVAC 模式

必须将设备更新为当前固件版本才能设置节能温度。

参数
HTTP 状态代码:400 请求错误
error必须先更新设备固件,然后才能更改 HVAC 模式。更新通常是在发布后一周内更新的。
typehttps://developers.nest.com/reference/error-messages#unsupported-firmware-version
message必须先更新设备固件,然后才能更改 HVAC 模式。更新通常是在发布后一周内更新的。

验证 WWN 字段时出错

参数
HTTP 状态代码:400 请求错误
error验证 WWN 字段时出错:$error
typehttps://developers.nest.com/reference/error-messages#where-id-internal
message验证 WWN 字段时出错:$error
details$error

预计到达时间是过去的时间

指定的预计到达时间是过去的时间(现在是 NOW 之前)。如需详细了解如何进行 ETA 调用,请参阅外出请求 ETA 指南

参数
HTTP 状态代码:400 请求错误
error预计到达时间是过去的时间:$estimatedArrivalTime=$estimatedArrivalTime, currentTime=$currentTime
typehttps://developers.nest.com/reference/error-messages#eta-in-the-past
message预计到达时间是过去的时间:$estimatedArrivalTime=$estimatedArrivalTime, currentTime=$currentTime
details$estimatedArrivalTime
$currentTime

预计到达时间太远

指定的预计到达时间不能超过未来 8 小时。如需详细了解如何进行 ETA 调用,请参阅外出请求 ETA 指南

参数
HTTP 状态代码:400 请求错误
error预计到达时间太远
typehttps://developers.nest.com/reference/error-messages#eta-too-far-in-the-future
message预计到达时间太远

未设置 fan_timer_active

未定义 fan_timer_active

参数
HTTP 状态代码:400 请求错误
error未设置 fan_timer_active
typehttps://developers.nest.com/reference/error-messages#fan-timer-active-value-missing
message未设置 fan_timer_active

禁止访问

用于访问 Nest 服务的凭据无效。

参数
HTTP 状态代码:403 禁止
error禁止访问
typehttps://developers.nest.com/reference/error-messages#forbidden
message禁止访问

内部错误

参数
HTTP 状态代码:500 内部服务器错误
error内部错误
typehttps://developers.nest.com/reference/error-messages#internal-error
message内部错误

摄像头 ID 无效

camera-id 无效。

参数
HTTP 状态代码:400 请求错误
error摄像头 ID $id 无效
typehttps://developers.nest.com/reference/error-messages#invalid-camera-id
message无效的摄像头 ID:$id
details$id

发送的内容无效

此调用包含无效内容。例如,对于布尔值变量,则使用“yes”而不是“true”。

参数
HTTP 状态代码:400 请求错误
error发送的内容无效
typehttps://developers.nest.com/reference/error-messages#invalid-content-sent
message发送的内容无效

Fragment 路径无效

部分请求路径无效。例如,对象或字段名称可能拼写错误。

参数
HTTP 状态代码:400 请求错误
error片段路径无效:$requestPath
typehttps://developers.nest.com/reference/error-messages#invalid-fragment
message片段路径无效:$requestPath
details$requestPath

HVAC 模式无效

恒温器的 HVAC 系统不支持该产品请求的模式:heatcoolheat-cool

参数
HTTP 状态代码:400 请求错误
error暖通空调模式无效:$mode
typehttps://developers.nest.com/reference/error-messages#invalid-mode
message暖通空调模式无效:$mode
details$mode

烟雾 + co 警报 ID 无效

smoke_co_alarm_id 无效。

参数
HTTP 状态代码:400 请求错误
error无效的烟雾 + 警报 ID $id
typehttps://developers.nest.com/reference/error-messages#invalid-smoke-co-alarm-id
message无效的烟雾 + 警报 ID:$id
details$id

结构 ID 无效

structure_id 无效。

参数
HTTP 状态代码:400 请求错误
error结构 ID $id 无效
typehttps://developers.nest.com/reference/error-messages#invalid-structure-id
message结构 ID 无效:$id
details$id

恒温器 ID 无效

thermostat_id 无效。

参数
HTTP 状态代码:400 请求错误
error恒温器 ID $id 无效
typehttps://developers.nest.com/reference/error-messages#invalid-thermostat-id
message无效的温控器 ID:$id
details$id

“Away”的值无效

您试图设置的 away 值无效。

参数
HTTP 状态代码:400 请求错误
error“Away”的值无效
typehttps://developers.nest.com/reference/error-messages#invalid-away-value
message无效值:$value。只能使用允许值“在家”和“外出”。
details$value

is_streaming 不是布尔值

产品尝试将 is-streaming 字段设置为非布尔值。

参数
HTTP 状态代码:400 请求错误
erroris_streaming 不是布尔值
typehttps://developers.nest.com/reference/error-messages#invalid-is-stream-format
messageis_streaming 不是布尔值

标签长度必须少于 256 个字符

产品尝试创建包含 256 个字符以上的 Thermostat 标签

参数
HTTP 状态代码:400 请求错误
error标签长度不得超过 $max_label_length 个字符
typehttps://developers.nest.com/reference/error-messages#max-label-length
message标签长度不得超过 $max_label_length 个字符
details$max_label_length

自定义元素数量超出上限

商品尝试创建超出上限的自定义 wheres 对象。允许的自定义 wheres 对象数量上限为 32。

参数
HTTP 状态代码:400 请求错误
error自定义项的数量已超出上限($max_where_count 个)
typehttps://developers.nest.com/reference/error-messages#max-where-count
message自定义项的数量已超出上限($max_where_count 个)
details$max_where_count

超出名称长度上限的自定义上限

name”过长。我们建议少于 30 个字符。

参数
HTTP 状态代码:400 请求错误
error自行指定的名称长度超出 $max_custom_where_name_length 的上限
typehttps://developers.nest.com/reference/error-messages#max-where-name-length
message自行指定的名称长度超出 $max_custom_where_name_length 的上限
details$max_custom_where_name_length

缺少字段

调用缺少必需的参数。

参数
HTTP 状态代码:400 请求错误
error缺少字段:$fieldName
typehttps://developers.nest.com/reference/error-messages#field-is-missing
message缺少字段:$fieldName
details$fieldName

缺少地点 ID

缺少 where_id 格式。

参数
HTTP 状态代码:400 请求错误
error地点缺失 ID
typehttps://developers.nest.com/reference/error-messages#where-id-missing
message地点缺失 ID

没有 HVAC 风扇

HVAC 系统似乎没有独立的风扇。

参数
HTTP 状态代码:400 请求错误
error没有暖通空调风扇
typehttps://developers.nest.com/reference/error-messages#no-hvac-fan
message没有暖通空调风扇

没有在线恒温器

恒温器目前处于离线状态启用 Wi-Fi 后,您的产品应重新获得访问权限。

参数
HTTP 状态代码:400 请求错误
error没有在线恒温器
typehttps://developers.nest.com/reference/error-messages#no-thermostats-online
message没有在线恒温器

没有已配对的设备

用户的 Nest 设备未与用户的 Nest 帐号配对

参数
HTTP 状态代码:400 请求错误
error没有已配对的设备
typehttps://developers.nest.com/reference/error-messages#no-paired-devices
message没有已配对的设备

没有可取消的有效预计到达时间

此行程无效,无法取消。

参数
HTTP 状态代码:400 请求错误
error没有可取消的有效预计到达时间
typehttps://developers.nest.com/reference/error-messages#no-valid-eta-to-cancel
message没有可取消的有效预计到达时间

没有字段的写入权限

客户端没有此数据的写入权限。如需了解详情,请参阅权限概览

参数
HTTP 状态代码:400 请求错误
error以下字段没有写入权限:$fields
typehttps://developers.nest.com/reference/error-messages#no-write-permission
message以下字段没有写入权限:$fields
details$fields

请求类型无效

请求类型无效。例如,当需要 PUT 时,系统会执行 POST 调用。

参数
HTTP 状态代码:400 请求错误
error请求类型无效:$requestType
typehttps://developers.nest.com/reference/error-messages#request-type-not-allowed
message请求类型无效:$requestType
details$requestType

未找到

调用尝试读取的路径不存在。

参数
HTTP 状态代码:404(未找到)
error未找到
typehttps://developers.nest.com/reference/error-messages#not-found
message未找到

不在外出模式下

进行 ETA 调用时,结构未处于外出模式。 只有在结构设置为“外出”时,才接受 ETA 调用。

参数
HTTP 状态代码:400 请求错误
error不在外出模式下
typehttps://developers.nest.com/reference/error-messages#not-in-away-mode
message不在外出模式下

无法写入

您尝试写入的字段是只读字段。

参数
HTTP 状态代码:400 请求错误
error无法写入
typehttps://developers.nest.com/reference/error-messages#not-writable
message无法写入

仅在需要提供姓名的情况下

wheres 调用中包含额外的字段。

参数
HTTP 状态代码:400 请求错误
error仅在需要提供姓名的情况下
typehttps://developers.nest.com/reference/error-messages#extra-fields
message仅在需要提供姓名的情况下

POST 不是有效请求类型

请求类型无效。例如,当需要 PUT 时,系统会执行 POST 调用。

参数
HTTP 状态代码:400 请求错误
errorPOST 不是有效请求类型
typehttps://developers.nest.com/reference/error-messages#invalid-request-type
messagePOST 不是有效请求类型

架构违规行为

与设备配对时出错。

参数
HTTP 状态代码:400 请求错误
error架构违规行为
typehttps://developers.nest.com/reference/error-messages#schema-violation-error
message架构违规行为

服务不可用

参数
HTTP 状态代码:503 服务不可用
error服务不可用
typehttps://developers.nest.com/reference/error-messages#service-unavailable
message服务不可用

结构体的配对设备数量已达上限

结构体已达到允许的设备数量上限

参数
HTTP 状态代码:400 请求错误
error结构体的配对设备数量已达上限
typehttps://developers.nest.com/reference/error-messages#max-number-devices-error
message结构体的配对设备数量已达上限

结构不归用户所有

structure_id 与记录的用户帐号不匹配。

参数
HTTP 状态代码:400 请求错误
error结构不归用户所有。
typehttps://developers.nest.com/reference/error-messages#structure-ownership-error-uri
message结构不归用户所有。

温度 C 过高,无法锁定温度

恒温器已被用户锁定,并且产品尝试设置的目标温度高于锁定温度范围。

参数
HTTP 状态代码:400 请求错误
error温度 C 为 $tempC,最高温度为锁定温度 $highLockTemp
typehttps://developers.nest.com/reference/error-messages#high-c-value-4-lock
message温度 C 为 $tempC,最高温度为锁定温度 $highLockTemp
details$tempC
$highLockTemp

温度 C 过低,无法锁定

恒温器已被用户锁定,并且产品尝试将目标温度设为低于锁定温度范围。

参数
HTTP 状态代码:400 请求错误
error温度 C $tempC 温度过低,无法锁定温度 $lowLockTemp
typehttps://developers.nest.com/reference/error-messages#low-c-value-4-lock
message温度 C $tempC 温度过低,无法锁定温度 $lowLockTemp
details$tempC
$lowLockTemp

温度 C 值过高

该产品试图设置的目标温度值对于摄氏度来说过高。如需了解允许使用的摄氏度范围,请参阅 target_temperature_c

参数
HTTP 状态代码:400 请求错误
error温度 C 的值过高:$tempC
typehttps://developers.nest.com/reference/error-messages#high-c-value
message温度 C 的值过高:$tempC
details$tempC

温度 C 值过低

该产品尝试设置的目标温度值过低,不能设为摄氏度。如需了解允许使用的摄氏度范围,请参阅 target_temperature_c

参数
HTTP 状态代码:400 请求错误
error温度 C 的值过低:$tempC
typehttps://developers.nest.com/reference/error-messages#low-c-value
message温度 C 的值过低:$tempC
details$tempC

温度 F 过高,无法锁定

恒温器已被用户锁定,并且产品试图将华氏温度设为高于锁定温度范围。

参数
HTTP 状态代码:400 请求错误
error温度 F $tempF,最高温度为锁定温度 $highLockTemp
typehttps://developers.nest.com/reference/error-messages#high-f-value-4-lock
message温度 F $tempF,最高温度为锁定温度 $highLockTemp
details$tempF
$highLockTemp

温度 F 过低,无法锁定

恒温器已被用户锁定,产品尝试设置的华氏温度低于锁定温度范围。

参数
HTTP 状态代码:400 请求错误
error温度 F 为 $tempF,最低温度为锁定温度 $lowLockTemp
typehttps://developers.nest.com/reference/error-messages#low-f-value-4-lock
message温度 F 为 $tempF,最低温度为锁定温度 $lowLockTemp
details$tempF
$lowLockTemp

温度 F 值过高

该产品尝试设置的目标温度值对于华氏温度来说过高。如需了解允许华氏度的温度范围,请参阅 target_temperature_f

参数
HTTP 状态代码:400 请求错误
error温度 F 值过高:$tempF
typehttps://developers.nest.com/reference/error-messages#high-f-value
message温度 F 值过高:$tempF
details$tempF

温度 F 值过低

产品尝试设置的目标温度值过低,无法用于华氏度。如需了解允许华氏度的温度范围,请参阅 target_temperature_f

参数
HTTP 状态代码:400 请求错误
error温度 F 值过低:$tempF
typehttps://developers.nest.com/reference/error-messages#low-f-value
message温度 F 值过低:$tempF
details$tempF

温度格式不正确

产品尝试为所选的 temperature_scale 使用错误的数字格式设置目标温度。摄氏度应该是以 0.5 度为增量的整数 (21.5),而华氏温度应为整数 (72)。

参数
HTTP 状态代码:400 请求错误
error温度“$temp”的格式不正确
typehttps://developers.nest.com/reference/error-messages#format-error
message温度“$temp”的格式不正确
details$temp

更新时无法修改字段

产品尝试写入只读字段。

参数
HTTP 状态代码:400 请求错误
error更新时无法修改以下字段:$fieldNames
typehttps://developers.nest.com/reference/error-messages#read-only-field-error
message更新时无法修改以下字段:$fieldNames
details$fieldNames

字段应采用 ISO 8601 格式

此字段未采用 ISO 8601 格式。

参数
HTTP 状态代码:400 请求错误
error字段应使用 ISO 8601 格式:$fieldNames
typehttps://developers.nest.com/reference/error-messages#time-format-error
message字段应使用 ISO 8601 格式:$fieldNames
details$fieldNames

恒温器未连接到网络

恒温器目前处于离线状态启用 Wi-Fi 后,您的产品应重新获得访问权限。

参数
HTTP 状态代码:400 请求错误
error恒温器未连接到网络
typehttps://developers.nest.com/reference/error-messages#not-online
message恒温器未连接到网络

此行程已被手动覆盖

用户已手动替换行程。

参数
HTTP 状态代码:400 请求错误
error此行程已被手动覆盖
typehttps://developers.nest.com/reference/error-messages#trip-manually-overidden
message此行程已被手动覆盖

无法创建位置 ID

缺少 wheres 对象。未定义 where_id 值。

参数
HTTP 状态代码:400 请求错误
error无法创建位置 ID
typehttps://developers.nest.com/reference/error-messages#wheres-missing
message无法创建位置 ID

未经授权

授权失败。

有几个条件可生成此错误消息:

  • 如果指定的 HTTP 实现未将授权标头自动转发到重定向的 URI,则会出现不正确的重定向。如需了解详情,请参阅如何处理重定向

  • 错误的权限。例如,尝试在仅为客户端选择相机权限时读取温控器端点。如需了解详情,请参阅如何选择权限

参数
HTTP 状态代码:401 Unauthorized
error未经授权
typehttps://developers.nest.com/reference/error-messages#auth-error
message未经授权

未知

参数
HTTP 状态代码:400 请求错误
error未知
typehttps://developers.nest.com/reference/error-messages#unknown
message未知

未知供应商/设备类型

在设备配对期间无法识别的供应商/设备。

参数
HTTP 状态代码:400 请求错误
error未知供应商/设备类型
typehttps://developers.nest.com/reference/error-messages#unknown-vendor-device-type-error
message未知供应商/设备类型

$fieldName 的值的类型有误

发送的数据类型有误。例如,预计会发送布尔值字符串。

参数
HTTP 状态代码:400 请求错误
error$fieldName”的值的类型有误
typehttps://developers.nest.com/reference/error-messages#wrong-data-type
message$fieldName”的值的类型有误
details$fieldName

名称已存在

产品尝试设置的 where_name 已存在。请使用新名称重试。

参数
HTTP 状态代码:400 请求错误
error名称“$name”已存在
typehttps://developers.nest.com/reference/error-messages#where-name-exists
message名称“$name”已存在
details$name

未提供名称

调用中缺少 where_name

参数
HTTP 状态代码:400 请求错误
error未提供名称
typehttps://developers.nest.com/reference/error-messages#where-name-missing
message未提供名称

当名称的长度为零时

其中 name 未定义(包含零个字符)。

参数
HTTP 状态代码:400 请求错误
error当名称的长度为零时
typehttps://developers.nest.com/reference/error-messages#zero-length-where-name
message当名称的长度为零时

其中,名称必须是字符串

where_name 发送的数据类型有误。例如,字符串应该有数字。

参数
HTTP 状态代码:400 请求错误
error其中,名称必须是字符串
typehttps://developers.nest.com/reference/error-messages#where-name-wrong-format
message其中,名称必须是字符串

where_id 不存在

where_id 无效。

参数
HTTP 状态代码:400 请求错误
errorwhere_id 不存在
typehttps://developers.nest.com/reference/error-messages#where-id-invalid
messagewhere_id 不存在
details$where_id

其中,where_id 必须是字符串

where_id 格式无效。例如,发送了一个数字(而非字符串)。

参数
HTTP 状态代码:400 请求错误
error其中,where_id 必须是字符串
typehttps://developers.nest.com/reference/error-messages#where-id-wrong-format
message其中,where_id 必须是字符串

其他错误代码和消息

设备错误代码

对于与 Nest API 无关的设备特定错误代码和消息,请参阅以下内容:

REST 错误代码

当您进行 REST API 调用时,系统会返回常见的 HTTP 状态代码。

REST 速率限制消息

使用 REST 时,如果您在短时间内发送过多调用,则可能会收到 429 过多请求 HTTP 响应状态代码。

如需了解详情,请参阅数据速率限制