# 错误信息（ Error Messages）

当Smart Home Skill API向您的技能适配器发送控制请求时，可能会出现不同种类的错误，如果需要，您的技能适配器应使用适当的错误类型和相应信息进行响应。然而，智能家居技能不需要返回每个错误类型; 只有那些符合发生故障类型的错误才需要返回。本节中列出了错误类型和详细信息。除非另有说明，否则错误消息不适用于设备发现，并且不应返回错误消息作为对DiscoverAppliancesRequest的响应。

用户错误：由于客户发出无效请求时导致的错误。例如，客户要求将恒温器设置为1000度。

ValueOutOfRangeError
TargetOfflineError
NoSuchTargetError
BridgeOfflineError

技能适配器错误：当请求有效，但由于硬件问题或限制，技能适配器无法完成所需的任务时，会发生这些错误。

DriverInternalError
DependentServiceUnavailableError
NotSupportedInCurrentModeError
RateLimitExceededError
TargetBridgeConnectivityUnstableError
TargetFirmwareOutdatedError
TargetBridgeFirmwareOutdatedError
TargetHardwareMalfunctionError
TargetBridgetHardwareMalfunctionError
TargetConnectivityUnstableError
TargetHardwareMalfunctionError
UnableToGetValueError
UnableToSetValueError
UnwillingToSetValueError

其他错误：当请求中的内容无法满足请求、认证令牌无效，或者技能适配器无法满足请求时的一些错误。

ExpiredAccessTokenError
InvalidAccessTokenError
UnsupportedTargetError
UnsupportedOperationError
UnsupportedTargetSettingError
UnexpectedInformationReceivedError

# 用户错误

当客户给出不正确的或腾讯小微无法完成的指示时，会发生以下错误。

# ValueOutOfRangeError

目的：表示客户请求将目标值设置为超出其支持范围的值。例如，一位客户问：“小微，将空调设置为1000度”。

Payload

属性	描述	是否必需
minimumValue	目标设备设置允许的最小值，double数值类型。	是
maximumValue	目标设备设置允许的最大值，double数值类型。	是

ValueOutOfRangeError示例：

    {
      "header":{
        "messageId": "9422676d-2356-4aa7-aa88-c642f12bfcd6",
        "namespace":"SmartHome.Control",
        "name":"ValueOutOfRangeError",
        "payloadVersion":"2"
      },
      "payload":{
        "minimumValue":15.0,
        "maximumValue":30.0
      }
    }

# TargetOfflineError

目的：表示目标设备未连接到客户的设备云或不在。

Payload

属性	描述	是否必需
None	无需返回任何字段。	N/A

TargetOfflineError示例：

    {
      "header":{
        "messageId": "9422676d-2356-4aa7-aa88-c642f12bfcd6",
        "namespace":"SmartHome.Control",
        "name":"TargetOfflineError",
        "payloadVersion":"2"
      },
      "payload":{
      }
    }

# NoSuchTargetError

目的：表示无法找到目标设备，意味着终端用户从未配置。

Payload

属性	描述	是否必需
None	无需返回任何字段。	N/A

NoSuchTargetError示例：

    {
      "header":{
        "messageId": "9422676d-2356-4aa7-aa88-c642f12bfcd6",
        "namespace":"SmartHome.Control",
        "name":"NoSuchTargetError",
        "payloadVersion":"2",
      },
      "payload":{
      }
    }

# BridgeOfflineError

目的：表示目标设备连接到已关闭电源的家庭自动化集线器或网桥。

Payload

属性	描述	是否必需
None	无需返回任何字段。	N/A

BridgeOfflineError示例：

    {
      "header":{
        "messageId": "9422676d-2356-4aa7-aa88-c642f12bfcd6",
        "namespace":"SmartHome.Control",
        "name":"BridgeOfflineError",
        "payloadVersion":"2",
      },
      "payload":{
      }
    }

# 技能适配器错误

当技能适配器与启用云的设备或设备云交互时出现问题时，会发生以下错误。在这些情况下，客户请求有效，但由于某种原因无法完成。

# DriverInternalError

目的：表示技能适配器中的通用运行时错误。如果可能，应该返回更具体的错误。

Payload

属性	描述	是否必需
None	无需返回任何字段。	N/A

DriverInternalError示例：

    {
      "header":{
        "messageId": "9422676d-2356-4aa7-aa88-c642f12bfcd6",
        "namespace":"SmartHome.Control",
        "name":"DriverInternalError",
        "payloadVersion":"2",
      },
      "payload":{
      }
    }

# DependentServiceUnavailableError

目的：表示技能适配器依赖的后端服务不可用，技能适配器无法完成请求。

Payload

属性	描述	是否必需
dependentServiceName	被依赖的不可用服务名。必须以字母数字字符和空格指定，超过256个字符将被截断。	是

DependentServiceUnavailableError示例：

    {
      "header":{
        "messageId": "9422676d-2356-4aa7-aa88-c642f12bfcd6",
        "namespace":"SmartHome.Control",
        "name":"DependentServiceUnavailableError",
        "payloadVersion":"2",
      },
      "payload":{
        "dependentServiceName":"Customer Credential Database"
      }
    }

# TargetConnectivityUnstableError

目的：表示目标设备的云连接不稳定可靠。

Payload

属性	描述	是否必需
None	无需返回任何字段。	N/A

TargetConnectivityUnstableError示例：

    {
      "header":{
        "messageId": "9422676d-2356-4aa7-aa88-c642f12bfcd6",
        "namespace":"SmartHome.Control",
        "name":"TargetConnectivityUnstableError",
        "payloadVersion":"2",
      },
      "payload":{
      }
    }

# TargetBridgeConnectivityUnstableError

目的：表示连接目标设备的家庭自动化集线器或网桥的云连接不稳定和不可靠。

Payload

属性	描述	是否必需
None	无需返回任何字段。	N/A

TargetBridgeConnectivityUnstableError示例：

    {
      "header":{
        "messageId": "9422676d-2356-4aa7-aa88-c642f12bfcd6",
        "namespace":"SmartHome.Control",
        "name":"TargetBridgeConnectivityUnstableError",
        "payloadVersion":"2",
      },
      "payload":{
      }
    }

# TargetFirmwareOutdatedError

目的：表示目标设备的固件已过期。

Payload

属性	描述	是否必需
minimumFirmwareVersion	表示最低允许的固件版本，不能超过256个字符。	是
currentFirmwareVersion	表示当前固件版本，不能超过256个字符。	是

TargetFirmwareOutdatedError示例：

    {
      "header":{
        "messageId": "9422676d-2356-4aa7-aa88-c642f12bfcd6",
        "namespace":"SmartHome.Control",
        "name":"TargetFirmwareOutdatedError",
        "payloadVersion":"2",
      },
      "payload":{
        "minimumFirmwareVersion":"17",
        "currentFirmwareVersion":"6"
      }
    }

# TargetBridgeFirmwareOutdatedError

**目的：**表示连接目标设备的家庭自动化集线器或网桥具有过时的固件。

Payload

属性	描述	是否必需
minimumFirmwareVersion	表示最低允许的固件版本，不能超过256个字符。	是
currentFirmwareVersion	表示当前固件版本，不能超过256个字符。	是

TargetBridgeFirmwareOutdatedError示例：

    {
      "header":{
        "messageId": "9422676d-2356-4aa7-aa88-c642f12bfcd6",
        "namespace":"SmartHome.Control",
        "name":"TargetBridgeFirmwareOutdatedError",
        "payloadVersion":"2",
      },
      "payload":{
        "minimumFirmwareVersion":"17",
        "currentFirmwareVersion":"6"
      }
    }

# TargetHardwareMalfunctionError

目的：表示目标设备遇到硬件故障。

Payload

属性	描述	是否必需
None	无需返回任何字段。	N/A

TargetHardwareMalfunctionError示例：

    {
      "header":{
        "messageId": "9422676d-2356-4aa7-aa88-c642f12bfcd6",
        "namespace":"SmartHome.Control",
        "name":"TargetHardwareMalfunctionError",
        "payloadVersion":"2",
      },
      "payload":{
      }
    }

# TargetBridgeHardwareMalfunctionError

目的：表示连接目标设备的家庭自动化集线器或桥接器出现硬件故障。

Payload

属性	描述	是否必需
None	无需返回任何字段。	N/A

TargetHardwareMalfunctionError示例：

    {
      "header":{
        "messageId": "9422676d-2356-4aa7-aa88-c642f12bfcd6",
        "namespace":"SmartHome.Control",
        "name":"TargetHardwareMalfunctionError",
        "payloadVersion":"2",
      },
      "payload":{
      }
    }

# UnableToGetValueError

目的：表示尝试在目标设备上获取指定值时发生错误。当返回此错误时，适当的errorInfo.code值使得小微能够适应不同类型的故障。您只需生成适用于目标设备的错误代码。

Payload

属性	描述	是否必需
errorInfo	描述为什么不能获取指定值的错误对象。	是
errorInfo.code	字符串格式的错误代码。有效值是：DEVICE_AJAR：由于门打开，无法获得指定的状态；DEVICE_BUSY：设备正忙；DEVICE_JAMMED：设备卡住；DEVICE_OVERHEATED：设备过热；HARDWARE_FAILURE：由于未确定的硬件故障，请求失败；LOW_BATTERY：设备的电池电量不足；NOT_CALIBRATED：设备未校准。	是
errorInfo.Description	来自设备制造商的错误的自定义描述。	否

UnableToGetValueError示例：

    {
      "header":{
        "messageId": "9422676d-2356-4aa7-aa88-c642f12bfcd6",
        "namespace":"SmartHome.Query",
        "name":"UnableToGetValueError",
        "payloadVersion":"2",
      },
      "payload":{
        "errorInfo":{
          "code":"DEVICE_JAMMED",
          "description":"A custom description of the error.."
        }
      }
    }

# UnableToSetValueError

目的：表示尝试在目标设备上设置指定值时发生错误。当返回此错误时，适当的errorInfo.code值使得小微能够适应不同类型的故障。您只需要生成适合于目标设备的错误代码。

Payload

属性	描述	是否必需
errorInfo	描述为什么不能设置值的错误对象。	是
errorInfo.code	字符串格式的错误代码。有效值是：DEVICE_AJAR：由于门打开，无法设置指定的状态；DEVICE_BUSY：设备正忙；DEVICE_JAMMED：设备卡住；DEVICE_OVERHEATED：设备过热；HARDWARE_FAILURE：由于未确定的硬件故障，请求失败；LOW_BATTERY：设备的电池电量不足；NOT_CALIBRATED：设备未校准。	是
errorInfo.Description	来自设备制造商的错误的自定义描述。	否

UnableToSetValueError示例：

    {
      "header":{
        "messageId": "9422676d-2356-4aa7-aa88-c642f12bfcd6",
        "namespace":"SmartHome.Control",
        "name":"UnableToSetValueError",
        "payloadVersion":"2",
      },
      "payload":{
        "errorInfo":{
          "code":"DEVICE_BUSY",
            "description":"A custom description of the error"
        }
      }
    }

# UnwillingToSetValueError

目的：表示目标设备制造商由于特定原因不愿意在指定的设备上设置请求的值。对温度设置使用此错误。

Payload

属性	描述	是否必需
errorInfo	描述为什么不能设置值的错误对象。	是
errorInfo.code	字符串格式的错误代码。目前，代码的有效值为ThermostatIsOff，表示由于恒温器关闭，制造商不愿自动将其启动，因此所请求的操作被拒绝。	是
errorInfo.description来自设备制造商的错误的自定义描述。	否

UnwillingToSetValueError示例：

    {
      "header":{
        "messageId": "9422676d-2356-4aa7-aa88-c642f12bfcd6",
        "namespace":"SmartHome.Control",
        "name":"UnwillingToSetValueError",
        "payloadVersion":"2",
      },
      "payload":{
        "errorInfo":{
          "code":"ThermostatIsOff",
          "description":"The requested operation is unsafe because it requires changing the mode."
        }
      }
    }

# RateLimitExceededError

目的：表示超出设备接受的最大请求数。此消息提供有关设备的最大请求数和这些请求的时间单位的信息。例如，如果设备每小时接受四个请求，则消息应分别指定4和HOUR作为rateLimit和timeUnit。

Payload

属性	描述	是否必需
rateLimit	一个整数，表示设备在指定的时间单位中接受的最大请求数。	是
timeUnit	一个字符串，表示rateLimit的时间单位，如MINUTE，HOUR或DAY。	是

RateLimitExceededError示例：

    {
      "header":{
        "messageId": "9422676d-2356-4aa7-aa88-c642f12bfcd6",
        "namespace":"SmartHome.Control",
        "name":"RateLimitExceededError",
        "payloadVersion":"2",
      },
      "payload":{
        "errorInfo":{
          "rateLimit":"10",
          "timeUnit":"HOUR"
        }
      }
    }

# NotSupportedInCurrentModeError

目的：表示目标设备处于无法通过Smart Home Skill API进行控制的模式，并提供有关设备当前模式的信息。对于指示灯，请将currentDeviceMode值设置为COLOR后返回此错误，以指示对当前设置为HSB颜色的指示灯进行了IncrementColorTemperature或DecrementColorTemperature请求。在这种情况下，小微回答说：“只有当你的灯光颜色被设置成白色时才能调整色温。”

Payload

属性	描述	是否必需
currentDeviceMode	表示设备当前模式的字符串。有效值为AUTO，AWAY，COLOR，COOL，HEAT和OTHER。	是

NotSupportedInCurrentModeError示例：

    {
      "header":{
        "messageId": "9422676d-2356-4aa7-aa88-c642f12bfcd6",
        "namespace":"SmartHome.Control",
        "name":"NotSupportedInCurrentModeError",
        "payloadVersion":"2",
      },
      "payload":{
        "currentDeviceMode":"AWAY"
      }

# 其他错误

当一个或多个请求输入无效并且技能适配器无法处理时，会发生以下错误。例如，认证令牌无效。

# ExpiredAccessTokenError

目的：表示用于认证的访问令牌已过期，不再有效。

Payload

属性	描述	是否必需
None	无需返回任何字段。	N/A

ExpiredAccessTokenError示例：

    {
      "header":{
        "messageId": "9422676d-2356-4aa7-aa88-c642f12bfcd6",
        "namespace":"SmartHome.Control",
        "name":"ExpiredAccessTokenError",
        "payloadVersion":"2",
      },
      "payload":{
      }

# InvalidAccessTokenError

目的：表示用于身份验证的访问令牌无效。令牌过期请使用ExpiredAccessTokenError。

Payload

属性	描述	是否必需
None	无需返回任何字段。	N/A

InvalidAccessTokenError示例：

    {
      "header":{
        "messageId": "9422676d-2356-4aa7-aa88-c642f12bfcd6",
        "namespace":"SmartHome.Control",
        "name":" InvalidAccessTokenError",
        "payloadVersion":"2",
      },
      "payload":{
      }

# UnsupportedTargetError

目的：表示技能适配器不支持目标设备。

Payload

属性	描述	是否必需
None	无需返回任何字段。	N/A

UnsupportedTargetError示例：

    {
      "header":{
        "messageId": "9422676d-2356-4aa7-aa88-c642f12bfcd6",
        "namespace":"SmartHome.Control",
        "name":"UnsupportedTargetError",
        "payloadVersion":"2",
      },
      "payload":{
      }

# UnsupportedOperationError

目的：表示目标设备不支持请求的操作。

Payload

属性	描述	是否必需
None	无需返回任何字段。	N/A

UnsupportedOperationError示例：

    {
      "header":{
        "messageId": "9422676d-2356-4aa7-aa88-c642f12bfcd6",
        "namespace":"SmartHome.Control",
        "name":" UnsupportedOperationError",
        "payloadVersion":"2",
      },
      "payload":{
      }

# UnsupportedTargetSettingError

目的：表示所请求的设置对于指定的设备和操作无效。

Payload

属性	描述	是否必需
None	无需返回任何字段。	N/A

UnsupportedTargetSettingError示例：

    {
      "header":{
        "messageId": "9422676d-2356-4aa7-aa88-c642f12bfcd6",
        "namespace":"SmartHome.Control",
        "name":"UnsupportedTargetSettingError",
        "payloadVersion":"2",
      },
      "payload":{
      }

# UnexpectedInformationReceivedError

目的：技能适配器由于请求消息中格式不正确或者意料之外的字段或者属性导致无法处理。

Payload

属性	描述	是否必需
faultingParameter	请求消息中格式不正确或者意料之外的字段或者属性。	是

UnexpectedInformationReceivedError示例：

    {
      "header":{
        "messageId": "9422676d-2356-4aa7-aa88-c642f12bfcd6",
        "namespace":"SmartHome.Control",
        "name":"UnexpectedInformationReceivedError",
        "payloadVersion":"2",
      },
      "payload":{
        "faultingParameter": "value"
      }