了解并解决 Azure IoT 中心错误

项目
01/30/2024

本文介绍在使用 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=*；配置：PrimaryThumbprint=*, SecondaryThumbprint=*
由于没有分配的权限，主体 user@example.com 无权进行 GET on /exampleOperation

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

SAS 令牌过期
IoT 中心会注意到过期，将设备断开连接并显示 401003 IoTHubUnauthorized
设备完成断开连接并显示 404104 DeviceConnectionClosedRemotely
IoT SDK 生成一个新的 SAS 令牌
设备成功重新连接到 IoT 中心

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

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

SDK 的默认令牌有效期为 60 分钟；但是，对于某些 SDK，令牌有效期和令牌续订阈值是可配置的。此外，设备在令牌续订时断开连接并重新连接时生成的错误对于每个 SDK 都是不同的。若要了解更多信息，并了解如何确定设备在日志中使用哪个 SDK，请参阅 Azure IoT SDK 的 MQTT 设备断开连接行为。

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

通常情况下，出现的错误消息应说明如何修复此错误。如果由于某种原因无法访问错误消息详细信息，请确保：

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

注意

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

通常，使用 NTP 执行时间同步或重启设备（可以在启动序列期间自动执行时间同步）可以修复问题并允许设备重新连接。若要避免此错误，请将设备配置为使用 NTP 执行定期时间同步。可以根据设备所经历的偏移量，将同步安排为每日、每周或每月进行。如果无法在设备上配置定期 NTP 同步，请安排定期重启。

403002 超出 IoT 中心配额

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

当超过 IoT 中心的每日消息配额时，会发生此错误。解决此问题的方法是：

升级或增加 IoT 中心的单位数，或等待下一 UTC 日期，以刷新每日配额。
若要了解如何将操作计入配额（如孪生查询和直接方法），请参阅了解 IoT 中心定价。
若要针对每日配额使用情况来设置监视，请设置一个警报，其指标为“使用的消息总数”。有关分步说明，请参阅使用 IoT 中心设置指标和警报。

当注册到 IoT 中心的设备数接近或超过 IoT 中心配额限制时，批量导入作业也可能返回此错误。了解详细信息，请参阅排除故障导入工作。

403004 超过设备最大队列深度

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

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

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

使用 HTTPS 的云到设备消息，其支持模式是间歇连接到设备，且不常检查消息（时间间隔小于 25 分钟）。若要降低遇到队列限制的可能性，请切换到 AMQP 或 MQTT（针对云到设备的消息）。

也可增强设备端的逻辑，以便快速完成、拒绝或放弃排队的消息，缩短生存时间，或者考虑发送较少的消息。请参阅 C2D 消息的生存时间。

最后，请考虑使用清除队列 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 中心可能遇到了暂时性问题。请参阅 IoT 中心内部服务器错误。

解决此问题的方法是：

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

我们建议使用 Azure IoT 设备 SDK 来可靠地管理连接。若要了解详细信息，请参阅使用 Azure IoT 中心设备 SDK 管理连接和可靠的消息传送

409001 设备已存在

尝试在 IoT 中心注册设备时，请求可能会失败且错误为 409001 DeviceAlreadyExists。

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

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

409002 链接创建冲突

除了知道设备断开连接或云到设备的消息失败，你可能还会在日志中看到错误 409002 LinkCreationConflict。

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

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

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

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

412002 设备消息锁丢失

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

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

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

429001 限制异常

对 IoT 中心的请求可能会失败，出现错误 429001 ThrottlingException。

发生此错误是因为已超过所请求操作的 IoT 中心限制。

要解决此错误，请根据上面指定的限制比较你的“遥测消息发送尝试次数”指标，检查你是否达到了限制。还可以检查“限制错误数” 指标。有关这些指标的信息，请参阅设备遥测指标。有关如何使用指标来帮助你监视 IoT 中心的信息，请参阅监视 IoT 中心。

只有在违反限制的时间过长的情况下，IoT 中心才返回 429 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 中心的内部错误，可能是暂时性的。请参阅 IoT 中心内部服务器错误。

要解决此错误，请参阅 IoT 中心内部服务器错误。

504101 网关超时

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

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

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