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

了解和解决 Azure IoT 中心错误

2025-07-23

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

400027 新连接时强制关闭连接

如果设备在使用 .NET SDK 和 MQTT 传输类型时断开连接，并将 Communication_Error 报告为 ConnectionStatusChangeReason，你可能会看到“400027 ConnectionForcefullyClosedOnNewConnection”错误。或者，设备到云的孪生操作（如读取或修补报告的属性）或直接方法调用失败，错误代码为 400027。

当另一个客户端使用相同的标识创建与 IoT 中心的新连接时，会发生此错误，因此 IoT 中心将关闭以前的连接。 IoT 中心不允许多个客户端使用同一身份进行连接。

若要解决此错误，请确保每个客户端都使用自己的标识连接到 IoT 中心。

401003 IoT 中心未经授权

在日志中，可能会看到这样一种情况：设备断开连接并出现“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 同步，请计划定期重启。

403002 超出 IoT 中心配额

对 IoT 中心的请求可能会失败，并出现错误“403002 IoTHubQuotaExceeded”。在 Azure 门户中，IoT 中心设备列表不会加载。

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

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

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

403004 超过设备最大队列深度

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

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

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

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

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

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

403006 超出设备最大活动文件上传限制

你可能会看到您的文件上传请求失败，错误代码为 403006 DeviceMaximumActiveFileUploadLimitExceeded，并带有消息“活动文件上传请求数不能超过10”。

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

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

404001 找不到设备

在云到设备 (C2D) 通信期间（例如 C2D 消息、孪生更新或直接方法），操作可能会失败且错误为“404001 DeviceNotFound”。

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

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

404103设备未联机

即使设备处于联机状态，对设备执行直接方法可能也会失败，并显示错误“404103 DeviceNotOnline”。

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

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

404104设备连接被远程关闭

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

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

或者，许多设备同时断开连接时，你会在“连接的设备 (connectedDeviceCount)”指标中看到一个 dip，在 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 内部错误。

若要解决此错误：

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

注释

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

409001设备已存在

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

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

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

409002 链接创建冲突

您可能会在日志中看到错误 409002 LinkCreationConflict，同时伴随设备断开连接或云到设备消息失败。

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

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

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

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

412002设备消息锁丢失

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

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

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

429xxx 限制异常

你可能会看到，对 IoT 中心的请求失败，出现以 429 开头的错误，例如：

429000 - 通用请求过多
429001 – ThrottlingException：请求的操作超出了流量限制。
429002 - ThrottleBacklogLimitExceeded：由于限制而积压的请求数已超过积压限度。
429003 - ThrottlingBacklogTimeout：请求因限制而被积压，在积压队列中等待时已超时。
429004 - ThrottlingMaxActiveJobCountExceeded
429005 – 设备限速上限已超出

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

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

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

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

500xxx 内部错误

你可能会看到，对 IoT 中心的请求失败，并出现以 500 和/或某种“服务器错误”开头的错误。一些可能性包括：

500001 ServerError：IoT 中心遇到了服务器端问题。
500008 GenericTimeout：IoT 中心无法在超时前完成连接请求。
ServiceUnavailable （无错误代码）：IoT 中心遇到内部错误。
InternalServerError （无错误代码）：IoT 中心遇到内部错误。

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

若要缓解 500xxx 错误，请在设备上执行重试操作。若要自动管理重试，请确保使用最新版本的 Azure IoT 中心 SDK。有关暂时性故障处理和重试的最佳做法的详细信息，请参阅暂时性故障处理。

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

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

找不到503003分区

你可能会看到对 IoT 中心的请求因 503003 PartitionNotFound 错误而失败。

此错误在 IoT 中心内部，可能是暂时性的。有关详细信息，请参阅 500xxx 内部错误。

若要解决此错误，请参阅 500xxx 内部错误。

504101 网关超时

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

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

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