你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

进行 Azure IoT Hub 错误代码的故障排除

本文介绍使用 IoT 中心时可能会遇到的常见错误代码的原因和解决方案。

400xxx 错误请求错误

你可能会发现对 IoT 中心的请求失败，出现以 400 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
400000 GenericBadRequest	一般错误的请求错误。	检查请求格式和参数。
400001 协议版本无效	不支持请求中指定的协议版本。	更新请求以使用受支持的协议版本。
400002 DeviceInvalidResultCount	设备返回的结果数无效。	确保设备返回正确的结果数。
400003 无效操作	请求的操作无效。	验证设备是否支持该操作。
400004 ArgumentInvalid	请求中的一个或多个参数无效。	检查请求参数是否正确。
400005 ArgumentNull	一个或多个必需参数为 null。	确保提供所有必需的参数。
400006 IotHubFormatError	请求的格式无效。	检查请求格式是否正确。
400007 设备存储实体序列化错误	无法序列化或反序列化设备存储实体。	验证序列化格式和数据。
400008 Blob容器验证错误	指定的 Blob 容器无效。	检查 Blob 容器名称和权限。
400009 ImportWarningExistsError	存在现有的导入警告。	查看导入警告并解决它们。
400010 无效的架构版本	指定的架构版本无效。	将架构版本更新为受支持的版本。
400011 DeviceDefinedMultipleTimes	设备已多次定义。	确保设备仅定义一次。
400012反序列化错误	反序列化请求时出错。	检查请求格式和数据是否正确。
400013 批量注册操作失败 BulkRegistryOperationFailure	批量注册操作失败。	查看批量操作的详细信息并重试。
400014 DefaultStorageEndpointNotConfigured	未配置默认存储终结点。	配置默认存储终结点。
400015 无效的文件上传关联ID	文件上传关联 ID 无效。	检查文件上传相关 ID 编号是否正确。
400016 过期文件上传关联ID	文件上传相关 ID 已过期。	获取新的文件上传关联 ID。
400017 无效存储端点	指定的存储终结点无效。	检查存储终结点是否正确。
400018 InvalidMessagingEndpoint	指定的消息传送终结点无效。	检查消息传送终结点是否正确。
400019 InvalidFileUploadCompletionStatus	文件上传完成状态无效。	检查文件上传完成状态是否正确。
400020 InvalidStorageEndpointOrBlob	尝试在文件上传期间创建 Blob 时，Blob 存储会返回`Forbidden`、`Unauthorized`、`NotFound`或`BadRequest`之一作为响应。	检查 Blob 存储权限和是否存在。
400021 请求已取消	请求已被取消。	重试请求。
400022 无效的存储终结点属性	指定的存储终结点属性无效。	检查存储终结点属性是否正确。
400023 EtagDoesNotMatch	请求中指定的 ETag 与资源的当前 ETag 不匹配。	更新请求中的 ETag 以匹配当前的 ETag。
400024 RequestTimedOut	请求超时。	重试请求。
400025 不支持对副本的操作	指定的副本不支持该操作。	查看操作和副本详细信息。
400026 NullMessage	消息为空。	确保消息不为 null 值。
400027 新连接上的连接被强制关闭	设备断开连接，并使用 .NET SDK 和 MQTT 传输类型将 `Communication_Error` 报告为`ConnectionStatusChangeReason`。设备到云孪生体操作（例如读取或修补报告的属性）或直接方法调用失败，错误代码为 `400027`。当另一个客户端使用相同的标识创建与 IoT 中心的新连接时，会发生此错误，因此 IoT 中心将关闭以前的连接。 IoT 中心不允许多个客户端使用同一身份进行连接。	确保每个客户端使用自己的标识连接到 IoT 中心。
400028 InvalidDeviceScope	指定的设备范围无效。	验证设备范围的准确性。
400029 ConnectionForcefullyClosedOnFaultInjection	在服务和平台升级期间，现有连接将因出现此错误而关闭。重试应该会立即成功。	重试该操作
400030 ConnectionRejectedOnFaultInjection	在服务和平台升级期间，新的连接和立即重试的尝试将被拒绝，并返回此错误。	重试该操作
400031 InvalidEndpointAuthenticationType (无效的终点身份验证类型)	指定的终结点身份验证类型无效。	检查终结点身份验证类型是否正确。
400032 ManagedIdentityNotEnabled	未启用托管标识。	启用托管标识。
400035 InvalidPolicyKey	指定的策略密钥无效。	检查策略密钥是否正确。
400036 批量重新生成设备密钥操作失败	批量重新生成设备密钥的操作失败。	查看操作详细信息。

4001xx 路由错误

你可能会看到，对 IoT 中心的请求失败，出现以 4001 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
400100 InvalidRouteTestInput	指定的路由测试输入无效。	检查路由测试输入是否正确。
400101 InvalidSourceOnRoute	路由上指定的源无效。	检查路由上的数据源是否正确。
400102 RoutingNotEnabled	未启用路由。	启用路由。
400103 InvalidContentEncodingOrType 内容编码或类型无效	指定的内容编码或类型无效。	检查内容编码或类型是否正确。

4003xx 模块错误

你可能会看到，对 IoT 中心的请求失败，并出现以 4003 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
400301 无法将模块注册到模块	不支持模块到模块通信。	请改用设备到云或云到设备的通信。
400302 TenantHubRoutingNotEnabled	未启用租户中心路由。	启用租户中心路由。

4004xx 配置错误

你可能会看到，对 IoT 中心的请求失败，出现以 4004 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
400401 无效的配置目标条件	配置中指定的目标条件无效。	检查目标条件是否正确。
400402 InvalidConfigurationContent	配置中指定的内容无效。	检查配置内容是否正确。
400403 无法修改不可变配置内容 (CannotModifyImmutableConfigurationContent)	配置内容是不可变的，无法修改。	请改为创建新的配置。
400404 InvalidConfigurationCustomMetricsQuery	配置中指定的自定义指标查询无效。	检查自定义指标查询是否正确。

4005xx 数字孪生接口错误

你可能会看到，对 IoT 中心的请求失败，出现以 4005 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
400501 InvalidPnPInterfaceDefinition	指定的接口定义无效。	检查接口定义是否正确。
400502 InvalidPnPDesiredProperties	指定的所需属性无效。	检查所需的属性是否正确。
400503 InvalidPnPReportedProperties	指定的报告属性无效。	检查报告的属性是否正确。
400504 InvalidPnPWritableReportedProperties	指定的可写报告属性无效。	检查可写的上报属性是否正确。
400505 InvalidDigitalTwinJsonPatch	为数字孪生指定的 JSON 修补程序无效。	检查 JSON 补丁是否正确。
400506 InvalidDigitalTwinPayload	为数字孪生指定的有效负载无效。	检查数字孪生有效负载是否正确。
400507 InvalidDigitalTwinPatch	为数字孪生指定的修补程序无效。	检查数字孪生体补丁是否正确。
400508 InvalidDigitalTwinPatchPath	为数字孪生指定的修补路径无效。	检查数字孪生补丁路径是否正确。

401xxx 未经授权错误

你可能会看到，对 IoT 中心的请求失败，出现以 401 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
401000 GenericUnauthorized	请求未被授权。	检查授权凭据。
401001 IotHubNotFound	找不到指定的 IoT 中心。	检查 IoT 中心名称和区域。
401002 IotHubUnauthorizedAccess	请求无权访问 IoT 中心。	检查 IoT 中心的访问策略和权限。
401003 IotHubUnauthorized	请求无权访问 IoT 中心。	有关详细信息，请参阅 401003 IotHubUnauthorized 错误。
401004 ElasticPoolNotFound	找不到指定的弹性池。	检查弹性池名称和区域。
401100 系统模块修改未授权访问	系统模块无权修改资源。	检查系统模块的权限。

401003 IotHubUnauthorized 错误

在日志中，你可能会看到以下模式：设备断开连接，并出现 401003 IoTHubUnauthorized，随后出现 404104 DeviceConnectionClosedRemotely，然后在不久后成功连接。

或者，对 IoT 中心的请求失败，并出现以下错误消息之一：

缺少 Authorization 标头
IotHub“*”不包含指定的设备“*”
授权规则 '*' 不允许访问 '*'
此设备的身份验证失败，续订令牌或证书并重新连接
指纹与配置不匹配：指纹：SHA1Hash=*，SHA2Hash=*；配置：主指纹=*、副指纹=*
由于没有分配的权限，主体 user@example.com 未获得 GET on /exampleOperation 的授权

发生此错误的原因是，对于 MQTT，某些 SDK 依赖于 IoT 中心在 SAS 令牌过期时发出断开连接，以了解何时刷新它。因此：

SAS 令牌过期
IoT 中心注意到到期，便断开设备与 401003 IoTHubUnauthorized 的连接。
设备已与 404104 DeviceConnectionClosedRemotely 断开连接
IoT SDK 生成新的 SAS 令牌
设备已成功重新连接到 IoT 中心

或者，IoT 中心无法对身份验证标头、规则或密钥进行身份验证。这一结果可能是由于症状中提到的任何原因造成的。

若要解决此错误，如果使用 IoT SDK 通过设备连接字符串进行连接，则无需执行任何作。 IoT SDK 重新生成新令牌，以在 SAS 令牌过期时重新连接。

默认令牌生存期跨 SDK 为 60 分钟;但是，对于某些 SDK，令牌的有效期和令牌续订阈值是可配置的。此外，当设备断开连接并重新连接令牌续订时生成的错误因每个 SDK 而异。若要了解更多信息以及如何确定设备在日志中使用哪个 SDK，请参阅监控、诊断和排查 Azure IoT 中心设备连接的Azure IoT SDK 的 MQTT 设备断开连接行为部分。

对于设备开发人员，如果担心错误数量太多，请切换到 C SDK，这会在 SAS 令牌过期之前续订它。对于 AMQP，SAS 令牌可以在不需要断开连接的情况下刷新。

通常，显示的错误消息应说明如何修复错误。如果出于某种原因而无法访问错误消息详细信息，请确保：

使用的 SAS 或其他安全令牌未过期。
对于 X.509 证书身份验证，设备证书或与设备关联的 CA 证书不会过期。若要了解如何向 IoT 中心注册 X.509 CA 证书，请参阅教程：创建和上传用于测试的证书。
对于 X.509 证书指纹身份验证，设备证书的指纹注册到 IoT 中心。
授权凭据的格式正确，适用于所使用的协议。若要了解详细信息，请参阅使用 Microsoft Entra ID 控制对 IoT 中心的访问。
使用的授权规则拥有请求的操作权限。
对于以“principal...”开头的最后一条错误消息，可以通过向用户分配正确的 Azure RBAC 权限级别来解决此错误。例如，IoT 中心的所有者可以分配“IoT 中心数据所有者”角色，该角色提供所有权限。请尝试此角色来解决缺少权限问题。

注释

当设备时间与服务器时间大于 5 分钟时，某些设备可能会遇到时间偏移问题。如果设备已连接到 IoT 中心并且数周甚至数月未出现问题，但后来开始不断拒绝其连接，则可能发生了此错误。该错误也可以特定于连接到 IoT 中心的设备子集，因为时间偏移可能以不同的速率发生，具体取决于设备首次连接或打开的时间。

通常，使用 NTP 执行时间同步或重新启动设备（它可以在启动序列期间自动执行时间同步）可修复此问题，并允许设备再次连接。若要避免此错误，请将设备配置为使用 NTP 执行定期时间同步。可以计划每日、每周或每月的同步，具体取决于设备体验的偏移量。如果无法在设备上配置定期 NTP 同步，请计划定期重启。

403xxx 禁止访问错误

你可能会看到，对 IoT 中心的请求失败，出现以 403 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
403000 GenericForbidden	请求被禁止。	检查请求权限。
403001 IotHubSuspended	IoT 中心已暂停。	检查 IoT 中心状态。
403002 IotHubQuotaExceeded	已超过 IoT 中心配额。	有关详细信息，请参阅 403002 IotHubQuotaExceeded 错误。
403003 JobQuotaExceeded	作业配额已超出。	检查作业配额和限制。
403004 DeviceMaximumQueueDepthExceeded 设备最大队列深度已超出	已超出设备的最大队列深度。	有关详细信息，请参阅 403004 DeviceMaximumQueueDepthExceeded 错误。
403005 IotHubMaxCbsTokenExceeded	已经超过 IoT 中心的最大 CBS 令牌限制。	检查 IoT 中心 CBS 令牌限制。
403006 DeviceMaximumActiveFileUploadLimitExceeded	已超出设备最大活动文件上传限制。	有关详细信息，请参阅 403006 DeviceMaximumActiveFileUploadLimitExceeded 错误。
403007 DeviceMaximumQueueSizeExceeded	已超出设备最大队列大小。	检查设备队列大小。
403008 RoutingEndpointResponseForbidden	路由终结点响应被禁止。	检查路由终结点权限。
403009 无效的消息到期时间	消息过期时间无效。	检查邮件过期时间设置。
403010 OperationNotAvailableInCurrentTier	在当前级别中此操作不可用。	检查 IoT Hub 的层级和功能。
403011 密钥加密密钥已吊销	密钥加密密钥已被吊销。	检查密钥加密密钥状态。
403012 设备已禁用	设备已禁用。	检查设备状态。
403800 DeviceMaximumInflightMethodExceeded	已经超过设备最大动态方法限制。	检查设备动态方法限制。

403002 IotHubQuotaExceeded 错误

你可能会看到向 IoT 中心发出的请求失败，并出现错误 403002 IotHubQuotaExceeded。在 Azure 门户中，IoT 中心设备列表不会加载。

当超过 IoT 中心的每日消息配额时，通常会发生此错误。若要解决此错误：

升级或增加 IoT 中心上的单位数，或等待下一 UTC 天刷新每日配额。
若要了解如何将操作计入配额（例如孪生查询和直接方法），请参阅 Azure IoT 中心计费信息中的“每次操作收费”部分。
若要监控每日配额使用情况，请设置警报，其中包含 所使用的消息总数。有关分步说明，请参阅教程的“设置指标 ”部分：设置和使用 IoT 中心的指标和日志。

当注册到 IoT 中心的设备数接近或超过 IoT 中心的配额限制时，批量导入作业也可能返回此错误。若要了解详细信息，请参阅批量导入和导出 IoT 中心设备标识的排查导入作业问题部分。

403004 DeviceMaximumQueueDepthExceeded 错误（设备最大队列深度超出）

尝试发送云到设备的消息时，你可能会看到请求失败并出现错误 403004 或 DeviceMaximumQueueDepthExceeded。

此错误根本原因是，设备的已排队消息数超出队列限制。

遇到此限制的最可能原因是使用 HTTPS 接收消息，这会导致使用 ReceiveAsync持续轮询，从而导致 IoT 中心限制请求。

使用 HTTPS 的云到设备消息支持的模式是间歇性连接的设备，这些设备不经常检查消息（不到每 25 分钟一次）。为了降低达到队列限制的可能性，请切换到 AMQP 或 MQTT 用于云到设备消息通信。

或者，增强设备端逻辑以快速完成、拒绝或放弃排队消息、缩短生存时间或考虑发送更少的消息。有关详细信息，请参阅《了解来自 IoT 中心的云到设备消息传送》的消息过期（生存时间）部分。

最后，请考虑使用清除队列 API，在达到限制之前定期清除挂起的消息。

403006 DeviceMaximumActiveFileUploadLimitExceeded 错误 (设备最大活动文件上传限制已超出)

你可能会看到文件上传请求失败并显示错误代码 403006 或 DeviceMaximumActiveFileUploadLimitExceeded 消息“活动文件上传请求数不能超过 10”。

发生此错误是因为每个设备客户端都受限于并发文件上传。如果设备在文件上传完成后未通知 IoT 中心，则可以轻松超过限制。不可靠的设备端网络通常会导致此问题。

若要解决此错误，请确保设备可以及时通知 IoT 中心文件上传完成。然后，尝试降低用于文件上传配置的 SAS 令牌 TTL。

4031xx 设备型号禁止访问错误

你可能会看到，对 IoT 中心的请求失败，出现以 4031 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
403100 DeviceModelMaxPropertiesExceeded - 设备模型的属性数量已超出上限	设备模型最大属性限制已超出。	检查设备模型属性。
403101 设备模型最大可索引属性超出限制	已超出设备模型最大可索引属性限制。	请检查设备模型的可索引属性。

404xxx NotFound 错误

你可能会看到，对 IoT 中心的请求失败，出现以 404 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
404000 GenericNotFound	找不到请求的资源。	检查资源 ID，然后重试。
404001 DeviceNotFound	找不到指定的设备。	有关详细信息，请参阅 404001 DeviceNotFound 错误。
404002 JobNotFound	找不到指定的作业。	检查任务 ID，然后重试。
404004 QuotaMetricNotFound 额度指标未找到	找不到指定的配额指标。	检查配额指标 ID，然后重试。
404005 SystemPropertyNotFound	找不到指定的系统属性。	检查系统属性 ID，然后重试。
404006 AmqpAddressNotFound	找不到指定的 AMQP 地址。	检查 AMQP 地址，然后重试。
404007 RoutingEndpointResponseNotFound	找不到指定的路由终结点响应。	检查路由终结点，然后重试。
404008 CertificateNotFound	找不到指定的证书。	检查证书 ID，然后重试。
404009 ElasticPoolTenantHubNotFound	找不到指定的弹性池租户中心。	检查弹性池租户中心 ID，然后重试。
404010 ModuleNotFound	找不到指定的模块。	检查模块 ID，然后重试。
404011 AzureTableStoreNotFound	找不到指定的 Azure 表格存储。	检查 Azure 表存储 ID，然后重试。
404012 IotHubFailingOver	IoT 中心正在进行故障转移。	检查 IoT 中心状态，然后重试。
404013 功能不支持	不支持请求的功能。	检查功能文档，然后重试。
404014 DigitalTwinInterfaceNotFound	找不到指定的数字孪生接口。	检查数字孪生接口 ID，然后重试。

404001 设备未找到错误

在云到设备（C2D）通信（如 C2D 消息、孪生更新或直接方法）期间，您可能会看到操作失败并出现错误 404001 DeviceNotFound。

作失败，因为 IoT 中心找不到设备。设备未注册或已禁用。

若要解决此错误，请注册所使用的设备 ID，然后重试。

4041xx 设备型号 NotFound 错误

你可能会看到，对 IoT 中心的请求失败，出现以 4041 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
404101 QueryStoreClusterNotFound	找不到指定的查询存储群集。	检查查询存储群集 ID，然后重试。
404102 DeviceNotOnline	指定的设备未联机。	有关详细信息，请参阅 404103 DeviceNotOnline 错误。
404104 DeviceConnectionClosedRemotely	设备连接已远程关闭。	有关详细信息，请参阅 404104 DeviceConnectionClosedRemotely 错误。

404103 DeviceNotOnline 错误

你可能会看到，即使设备处于联机状态，指向设备的直接方法也会失败并出现错误 404103 DeviceNotOnline 。

如果您知道设备处于在线状态，但仍然收到错误信息，则可能是由于设备上未注册直接方法的回调函数导致的。

有关为直接方法回调正确配置设备的详细信息，请参阅在设备上处理直接方法的在设备上处理直接方法部分。

设备连接被远程关闭错误代码404104

你可能会看到设备定期断开连接（例如，每 65 分钟），并在 404104 DeviceConnectionClosedRemotely IoT 中心资源日志中看到。有时，你还会看到 401003 IoTHubUnauthorized 和不到一分钟后出现的成功设备连接事件。

或者，设备会随机断开连接，并在 IoT 中心资源日志中看到404104 DeviceConnectionClosedRemotely。

或者，您可能会发现许多设备同时断开连接，并且您会看到连接的设备（connectedDeviceCount）指标出现下降，Azure Monitor 日志中出现比平常更多的 404104 DeviceConnectionClosedRemotely 和 500xxx 内部错误。

发生此错误的原因是用于连接到 IoT 中心的 SAS 令牌已过期，这会导致 IoT 中心断开设备的连接。当设备刷新令牌时，将重新建立连接。例如，默认情况下，对于 C SDK，SAS 令牌每小时过期一次，这可能会导致定期断开连接。若要了解详细信息，请参阅 401003 IoTHubUnauthorized 错误。

其他一些可能性包括：

设备失去基础网络连接的时间超过了 MQTT keep-alive 时长，导致远程空闲超时。每个设备的 MQTT keep-alive 设置可能不同。
设备发送了一个 TCP/IP 级重置，但是未发送应用程序级 MQTT DISCONNECT。从根本上说，设备突然关闭了基础套接字连接。有时，旧版 Azure IoT SDK 中的 bug 可能会导致此问题。
设备端应用程序崩溃。

或者，IoT 中心可能会遇到暂时性问题。有关详细信息，请参阅 500xxx 内部错误。

若要解决此错误：

请查看 401003 IoTHubUnauthorized 错误的指南。
通过测试连接，确保设备与 IoT 中心建立良好的连接。如果网络不可靠或时断时续，我们不建议增大 keep-alive 值，因为这可能会导致检测（例如通过 Azure Monitor 警报）花费更长时间。
使用最新版本的 Azure IoT 中心 SDK。
请参阅 500xxx 内部错误的指南。

注释

我们建议使用 Azure IoT 设备 SDK 来可靠地管理连接。若要了解详细信息，请参阅管理设备重新连接以创建可复原的应用程序

4043xx 配置 NotFound 错误

你可能会看到，对 IoT 中心的请求失败，出现以 4043 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
404301 ConfigurationNotFound	找不到指定的配置。	检查配置 ID，然后重试。
404302 GroupNotFound	找不到指定的组。	检查组 ID，然后重试。

4044xx PnP NotFound 错误

你可能会看到，对 IoT 中心的请求失败，出现以 4044 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
404401 DigitalTwinModelNotFound	找不到指定的数字孪生模型。	检查数字孪生模型 ID，然后重试。
404402 InterfaceNameModelNotFound	找不到指定的接口名称模型。	检查接口名称模型 ID，然后重试。

405xxx MethodNotAllowed 错误

你可能会看到，对 IoT 中心的请求失败，出现以 405 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
405000 通用方法不允许	不允许使用指定的方法。	检查方法，然后重试。

4051xx 设备型号 MethodNotAllowed 错误

你可能会发现对 IoT 中心的请求失败，并出现以 4051 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
405102 当前状态不允许操作	当前状态下不允许进行此操作。	检查设备状态，然后重试。
405103 ImportDevicesNotSupported	不支持导入设备。	检查导入设置，然后重试。
405104 BulkAddDevicesNotSupported	不支持批量添加设备。	检查批量添加设置，然后重试。

409xxx 冲突错误

你可能会看到，对 IoT 中心的请求失败，出现以 409 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
409000 GenericConflict	发生冲突。	检查请求，然后重试。
409001 设备已存在	指定的设备已存在。	有关详细信息，请参阅 409001 DeviceAlreadyExists 错误。
409002 链接创建冲突	创建链接时发生冲突。	有关详细信息，请参阅 409002 LinkCreationConflict 错误。
409003 CallbackSubscriptionConflict	回调订阅发生冲突。	检查回调订阅设置，然后重试。

409001 设备已存在错误

尝试在 IoT 中心注册设备时，可能会看到请求失败并出现错误 409001 DeviceAlreadyExists。

发生此错误的原因是 IoT 中心中已有具有相同设备 ID 的设备。

若要解决此错误，请使用其他设备 ID，然后重试。

409002 LinkCreationConflict 错误

日志中可能会出现错误 409002 LinkCreationConflict，以及设备断开连接或云到设备消息失败。

通常，当 IoT 中心检测到客户端有多个连接时，会发生此错误。事实上，当新的连接请求到达具有现有连接的设备时，IoT 中心会关闭现有连接，并出现此错误。

在最常见的情况下，单个问题（如 404104 设备远程关闭连接错误）会导致设备断开连接。设备尝试立即重新建立连接，但 IoT 中心仍认为设备已连接。 IoT 中心关闭以前的连接并记录此错误。

或者，设备端逻辑出现故障会导致设备在连接已打开的情况下建立连接。

若要解决此错误，请在日志中查找可以排除的其他错误，因为此错误通常显示为其他暂时性问题的副作用。否则，请确保仅在连接断开时发出新的连接请求。

4091xx 设备模型冲突错误

你可能会看到，对 IoT 中心的请求失败，并出现以 4091 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
409101 模型已存在	指定的模型已存在。	检查模型 ID，然后重试。
409102 DeviceLocked	指定的设备已锁定。	检查设备状态，然后重试。
409103 DeviceJobAlreadyExists	指定的设备作业已存在。	检查设备作业 ID，然后重试。
409104 JobAlreadyExists	指定的作业已存在。	检查任务 ID，然后重试。

4093xx 模块冲突错误

你可能会看到，对 IoT 中心的请求失败，出现以 4093 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
409301 模块已存在于设备上	设备上已存在指定的模块。	检查模块 ID，然后重试。

4094xx 配置冲突错误

你可能会看到，对 IoT 中心的请求失败，出现以 4094 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
409401 ConfigurationAlreadyExists	指定的配置已存在。	检查配置 ID，然后重试。
409402 ApplyConfigurationAlreadyInProgressOnDevice	指定的配置应用程序已在设备上进行。	检查设备状态，然后重试。

4095xx 数字孪生冲突错误

你可能会看到，对 IoT 中心的请求失败，并出现以 4095 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
409501 数字孪生模型已存在	指定的数字孪生模型已存在。	检查数字孪生模型 ID，然后重试。
409502 数字孪生模型存在于其他模型类型中	指定的数字孪生模型具有不同的模型类型。	检查数字孪生模型类型，然后重试。
409503 接口名称模型已存在	指定的接口名称模型已存在。	检查接口名称模型 ID，然后重试。

412xxx 前置条件失败错误

你可能会看到，对 IoT 中心的请求失败，出现以 412 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
412000 GenericPreconditionFailed（通用前置条件失败）	通用前置条件失败。	检查请求，然后重试。
412001 前置条件失败	前置条件失败。	检查请求，然后重试。
412002 DeviceMessageLockLost - 设备消息锁丢失	设备消息锁已丢失。	有关详细信息，请参阅 412002 DeviceMessageLockLost 错误。
412003 JobRunPreconditionFailed	作业运行前提条件失败。	检查作业状态，然后重试。
412004 InflightMessagesInLink	链接中存在即时消息。	检查链接状态，然后重试。

412002 DeviceMessageLockLost 错误

尝试发送云到设备的消息时，你可能会看到请求失败并出现错误 412002 DeviceMessageLockLost。

发生此错误的原因是，当设备从队列（例如，使用 ReceiveAsync()）收到云到设备的消息时，IoT 中心会将消息锁定，锁定超时时间为1分钟。如果在锁定超时过期后设备尝试完成消息，则 IoT 中心会引发此异常。

如果 IoT 中心在一分钟的锁定超时期限内没有收到通知，则会将该消息设置回“已排队”状态。设备可以尝试再次接收消息。若要防止将来发生错误，请实现设备端逻辑，以便在收到消息后的一分钟内完成消息。此一分钟的暂停无法更改。

413xxx：请求实体过大错误

你可能会看到，对 IoT 中心的请求失败，出现以 413 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
413000 GenericRequestEntityTooLarge	请求实体太大。	减小请求实体的大小，然后重试。
413001 MessageTooLarge	消息过大。	减小消息的大小，然后重试。
413002 TooManyDevices	注册的设备过多。	减少设备数量，然后重试。
413003 TooManyModulesOnDevice	设备上注册了太多模块。	减少模块数，然后重试。
413101 ConfigurationCountLimitExceeded	配置项数量已超出限制。	减少配置数，然后重试。
413201 DigitalTwinModelCountLimitExceeded	已超出数字孪生模型计数限制。	减少数字孪生模型的数量，然后重试。
413202 接口名称压缩模型数量超出限制	接口名称压缩模型的计数上限已超出。	减少接口名称压缩模型的数量，然后重试。

415xxx 不支持的媒体类型错误

你可能会看到，对 IoT 中心的请求失败，出现以 415 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
415000 通用不支持的媒体类型	媒体类型不受支持。	检查媒体类型，然后重试。
415101 数据类型不兼容 (IncompatibleDataType)	数据类型不兼容。	检查数据类型，然后重试。

429xxx 限制异常错误

你可能会看到，对 IoT 中心的请求失败，出现以 429 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
429000 GenericTooManyRequests	发出了太多请求。	减少请求数，然后重试。
429001 ThrottlingException	发生限制异常。	获取更多信息，请参阅流量限制文档。
429002 ThrottleBacklogLimitExceeded	由于限流造成的积压请求数已超过积压限制。	减少请求数，然后重试。请参阅流量整形文档，以了解在发送限流响应之前，流量调节的工作原理的详细信息。
429003 节流积压超时 (ThrottlingBacklogTimeout)	由于限制而积压的请求在积压队列中等待时已超时。	减少请求数，然后重试。
429004 ThrottlingMaxActiveJobCountExceeded	已经超过最大活动作业数。	减少活动作业数量，然后重试。
429005 DeviceThrottlingLimitExceeded	已经超过设备限制。	减少来自设备的请求数，然后重试。

如果超出请求操作的节流限制，则会发生这些错误。

你只能在限制错误数指标下通过 Azure Monitor 监视 429001 ThrottlingException 错误。目前，其他限制错误没有关联的指标，但会在日志中记录。

若要解决这些错误，请检查您是否达到了节流限制，方法是将 遥测消息发送尝试 指标与之前指定的限制进行比较。还可以检查 节流错误数量指标。有关这些指标的信息，请参阅设备遥测指标。有关如何使用指标来帮助监视 IoT 中心的信息，请参阅监视 Azure IoT 中心。

仅当违反限制过长一段时间后，IoT 中心才会返回 429001 ThrottlingException 。设置此延迟是为了在 IoT 中心接收到突发流量时防止消息丢失。在此期间，IoT 中心会按操作受限速率处理消息。如果积压了太多流量，则处理起来可能需要很长时间。有关详细信息，请参阅 IoT 中心配额和限制的流量整形部分。

如果达到配额或节流限制，考虑纵向扩展 IoT 中心。

499xxx 客户端关闭请求错误

你可能会看到，对 IoT 中心的请求失败，出现以 499 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
499000 ClientClosedRequest (客户端关闭请求)	客户端关闭了请求。	请稍后重试。

500xxx 内部服务器错误

你可能会看到，对 IoT 中心的请求失败，出现以 500 开头的错误或提及服务器错误。一些可能性包括：

错误代码	Description
500001 ServerError	出现服务器端错误。
500008 GenericTimeout	IoT 中心未能在超时之前完成连接请求。
ServiceUnavailable （无错误代码）	IoT 中心遇到内部错误。
InternalServerError （无错误代码）	IoT 中心遇到内部错误。

500xxx 错误响应的原因有很多。在所有情况下，问题很可能是暂时性的。虽然 IoT 中心团队努力维护 SLA，但 IoT 中心节点的小子集偶尔会遇到暂时性故障。当设备尝试连接到出现问题的节点时，将收到此错误。

要缓解 5000xx 错误，请从设备发出重试。若要自动管理重试，请确保使用最新版本的 Azure IoT 中心 SDK。有关暂时性故障处理和重试的最佳做法的详细信息，请参阅暂时性故障处理。

如果问题仍然存在，请检查资源运行状况和 Azure 状态，以查看 IoT 中心是否存在已知问题。也可使用手动故障转移功能。

如果没有已知问题，问题仍然存在，请联系支持人员进行进一步调查。

你可能会看到对 IoT 中心的请求失败，并出现以 5003 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
500301 ModelRepoEndpointError	模型存储库终结点无效。	检查模型存储库终结点，然后重试。
500302 ResolutionError	发生分辨率错误。	请稍后重试。

你可能会发现对 IoT 中心的请求失败，出现以 5004 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
500401 无法获取凭据	无法提取凭据。	检查凭据，然后重试。
500402 无法获取租户信息	无法提取租户信息。	检查租户信息，然后重试。
500403 无法分享身份	无法共享身份。	检查标识共享设置，然后重试。

你可能会看到，对 IoT 中心的请求失败，出现以 5005 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
500501 UnableToExpandDiscoveryInfo	无法展开发现信息。	检查发现信息，然后重试。
500502 UnableToExpandComponentInfo	无法展开组件信息。	检查组件信息，然后重试。
500503 无法压缩组件信息 UnableToCompressComponentInfo	无法压缩组件信息。	检查组件信息，然后重试。
500504 UnableToCompressDiscoveryInfo	无法压缩发现信息。	检查发现信息，然后重试。
500505 OrphanDiscoveryDocument	找到了孤立发现文档。	检查发现文档，然后重试。

你可能会发现对 IoT 中心的请求失败，并出现以 502 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
502000 GenericBadGateway	发生了一个一般“错误的网关”错误。	请稍后重试。

你可能会发现对 IoT 中心的请求失败，并出现以 503 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
503000 GenericServiceUnavailable	发生泛型服务不可用错误。	请稍后重试。
503001 ServiceUnavailable	服务不可用。	请稍后重试。
503004 IoT Hub 激活失败	IoT 中心激活失败。	检查 IoT 中心状态，然后重试。
503005 ServerBusy	服务器繁忙。	请稍后重试。
503006 IotHubRestoring	IoT 中心正在恢复。	请稍后重试。
503008 ReceiveLinkOpensThrottled	打开接收链接受到限制。	请稍后重试。

5031xx 设备型号不可用错误

你可能会看到，对 IoT 中心的请求失败，出现以 5031 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
503101 ConnectionUnavailable	连接不可用。	检查连接，然后重试。
503102 DeviceUnavailable	设备不可用。	检查设备状态，然后重试。

5032xx 配置不可用错误

你可能会看到对 IoT 中心的请求失败，并出现以 5032 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
503201 配置不可用	当前配置不可用。	检查配置，然后重试。
503202 GroupNotAvailable	组不可用。	请检查群组，然后重试。

你可能会发现对 IoT 中心的请求失败，并出现以 5033 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
503301 HostingServiceNotAvailable	托管服务不可用。	请稍后重试。

你可能会看到，对 IoT 中心的请求失败，出现以 504 开头的错误。下表列出了错误代码、其说明和可能的解决方案。

错误代码	Description	解决方案
504000 GenericGatewayTimeout	发生通用网关超时错误。	请稍后重试。
504101 GatewayTimeout	网关超时。	有关 504101 GatewayTimeout 错误的详细信息，请参阅。

504101 GatewayTimeout 错误

尝试将直接方法从 IoT 中心调用到设备时，可能会看到请求失败并出现错误 504101 GatewayTimeout。

发生此错误的原因是 IoT 中心遇到错误，无法确认直接方法是否在超时之前完成。或者，使用早期版本的 Azure IoT C# SDK （<1.19.0）时，设备与 IoT 中心之间的 AMQP 链接可能会因 bug 而以无提示方式删除。

若要解决此错误，请重试或升级到最新版本的 Azure IOT C# SDK。

反馈

此页面是否有帮助？

Last updated on 2026-01-07