Troubleshoot Azure IoT Hub error codes

This article describes the causes and solutions for common error codes that you might encounter while using IoT Hub.

400xxx Bad request errors

You might see that your requests to IoT Hub fail with an error that begins with 400. The following table lists the error codes, their descriptions, and possible solutions.

4001xx Routing errors

You might see that your requests to IoT Hub fail with an error that begins with 4001. The following table lists the error codes, their descriptions, and possible solutions.

4003xx Modules errors

You might see that your requests to IoT Hub fail with an error that begins with 4003. The following table lists the error codes, their descriptions, and possible solutions.

4004xx Configurations errors

You might see that your requests to IoT Hub fail with an error that begins with 4004. The following table lists the error codes, their descriptions, and possible solutions.

4005xx Digital twin interfaces errors

You might see that your requests to IoT Hub fail with an error that begins with 4005. The following table lists the error codes, their descriptions, and possible solutions.

401xxx Unauthorized errors

You might see that your requests to IoT Hub fail with an error that begins with 401. The following table lists the error codes, their descriptions, and possible solutions.

401003 IotHubUnauthorized error

In logs, you might see a pattern of devices disconnecting with 401003 IoTHubUnauthorized, followed by 404104 DeviceConnectionClosedRemotely, and then successfully connecting shortly after.

Or, requests to IoT Hub fail with one of the following error messages:

• Authorization header missing
• IotHub '*' does not contain the specified device '*'
• Authorization rule '*' does not allow access for '*'
• Authentication failed for this device, renew token or certificate and reconnect
• Thumbprint does not match configuration: Thumbprint: SHA1Hash=*, SHA2Hash=*; Configuration: PrimaryThumbprint=*, SecondaryThumbprint=*
• Principal user@example.com is not authorized for GET on /exampleOperation due to no assigned permissions

This error occurs because, for MQTT, some SDKs rely on IoT Hub to issue the disconnect when the SAS token expires to know when to refresh it. So:

1. The SAS token expires
2. IoT Hub notices the expiration, and disconnects the device with 401003 IoTHubUnauthorized
3. The device completes the disconnection with 404104 DeviceConnectionClosedRemotely
4. The IoT SDK generates a new SAS token
5. The device reconnects with IoT Hub successfully

Or, IoT Hub couldn't authenticate the auth header, rule, or key. This result could be due to any of the reasons cited in the symptoms.

To resolve this error, no action is needed if using IoT SDK for connection using the device connection string. IoT SDK regenerates the new token to reconnect on SAS token expiration.

The default token lifespan is 60 minutes across SDKs; however, for some SDKs the token lifespan and the token renewal threshold is configurable. Additionally, the errors generated when a device disconnects and reconnects on token renewal differs for each SDK. To learn more, and for information about how to determine which SDK your device is using in logs, see the MQTT device disconnect behavior with Azure IoT SDKs section of Monitor, diagnose, and troubleshoot Azure IoT Hub device connectivity.

For device developers, if the volume of errors is a concern, switch to the C SDK, which renews the SAS token before expiration. For AMQP, the SAS token can refresh without disconnection.

In general, the error message presented should explain how to fix the error. If for some reason you don't have access to the error message detail, make sure:

• The SAS or other security token you use isn't expired.
• For X.509 certificate authentication, the device certificate or the CA certificate associated with the device isn't expired. To learn how to register X.509 CA certificates with IoT Hub, see Tutorial: Create and upload certificates for testing.
• For X.509 certificate thumbprint authentication, the thumbprint of the device certificate is registered with IoT Hub.
• The authorization credential is well formed for the protocol that you use. To learn more, see Control access to IoT Hub by using Microsoft Entra ID.
• The authorization rule used has the permission for the operation requested.
• For the last error messages beginning with "principal...", this error can be resolved by assigning the correct level of Azure RBAC permission to the user. For example, an Owner on the IoT Hub can assign the "IoT Hub Data Owner" role, which gives all permissions. Try this role to resolve the lack of permission issue.

403xxx Forbidden errors

You might see that your requests to IoT Hub fail with an error that begins with 403. The following table lists the error codes, their descriptions, and possible solutions.

403002 IotHubQuotaExceeded error

You might see requests to IoT Hub fail with the error 403002 IotHubQuotaExceeded. And in Azure portal, the IoT hub device list doesn't load.

This error typically occurs when the daily message quota for the IoT hub is exceeded. To resolve this error:

• Upgrade or increase the number of units on the IoT hub or wait for the next UTC day for the daily quota to refresh.
• To understand how operations are counted toward the quota, such as twin queries and direct methods, see the Charges per operation section of Azure IoT Hub billing information.
• To set up monitoring for daily quota usage, set up an alert with the metric Total number of messages used. For step-by-step instructions, see the Set up metrics section of Tutorial: Set up and use metrics and logs with an IoT hub.

A bulk import job might also return this error when the number of devices registered to your IoT hub approaches or exceeds the quota limit for an IoT hub. To learn more, see the Troubleshoot import jobs section of Import and export IoT Hub device identities in bulk.

403004 DeviceMaximumQueueDepthExceeded error

When trying to send a cloud-to-device message, you might see that the request fails with the error 403004 or DeviceMaximumQueueDepthExceeded.

The underlying cause of this error is that the number of messages enqueued for the device exceeds the queue limit.

The most likely reason that you're running into this limit is because you're using HTTPS to receive the message, which leads to continuous polling using ReceiveAsync, resulting in IoT Hub throttling the request.

The supported pattern for cloud-to-device messages with HTTPS is intermittently connected devices that check for messages infrequently (less than every 25 minutes). To reduce the likelihood of running into the queue limit, switch to AMQP or MQTT for cloud-to-device messages.

Alternatively, enhance device side logic to complete, reject, or abandon queued messages quickly, shorten the time to live, or consider sending fewer messages. For more information, see the Message expiration (time to live) section of Understand cloud-to-device messaging from an IoT hub.

Lastly, consider using the Purge Queue API to periodically clean up pending messages before the limit is reached.

403006 DeviceMaximumActiveFileUploadLimitExceeded error

You might see that your file upload request fails with the error code 403006 or DeviceMaximumActiveFileUploadLimitExceeded and a message "Number of active file upload requests cannot exceed 10".

This error occurs because each device client is limited for concurrent file uploads. You can easily exceed the limit if your device doesn't notify IoT Hub when file uploads are completed. An unreliable device side network commonly causes this problem.

To resolve this error, ensure that the device can promptly notify IoT Hub file upload completion. Then, try reducing the SAS token TTL for file upload configuration.

4031xx Device model forbidden errors

You might see that your requests to IoT Hub fail with an error that begins with 4031. The following table lists the error codes, their descriptions, and possible solutions.

404xxx NotFound errors

You might see that your requests to IoT Hub fail with an error that begins with 404. The following table lists the error codes, their descriptions, and possible solutions.

404001 DeviceNotFound error

During a cloud-to-device (C2D) communication, such as C2D message, twin update, or direct method, you might see that the operation fails with error 404001 DeviceNotFound.

The operation failed because IoT Hub can't find the device. The device either isn't registered or is disabled.

To resolve this error, register the device ID that you used, then try again.

4041xx Device model NotFound errors

You might see that your requests to IoT Hub fail with an error that begins with 4041. The following table lists the error codes, their descriptions, and possible solutions.

404103 DeviceNotOnline error

You might see that a direct method to a device fails with the error 404103 DeviceNotOnline even if the device is online.

If you know that the device is online and still get the error, then the error likely occurred because the direct method callback isn't registered on the device.

For more information about configuring your device properly for direct method callbacks, see the Handle a direct method on a device section of Handle a direct method on a device.

404104 DeviceConnectionClosedRemotely error

You might see that devices disconnect at a regular interval (every 65 minutes, for example) and you see 404104 DeviceConnectionClosedRemotely in IoT Hub resource logs. Sometimes, you also see 401003 IoTHubUnauthorized and a successful device connection event less than a minute later.

Or, devices disconnect randomly, and you see 404104 DeviceConnectionClosedRemotely in IoT Hub resource logs.

Or, many devices disconnect at once, you see a dip in the Connected devices (connectedDeviceCount) metric, and there are more 404104 DeviceConnectionClosedRemotely and 500xxx Internal errors in Azure Monitor Logs than usual.

This error can occur because the SAS token used to connect to IoT Hub expired, which causes IoT Hub to disconnect the device. The connection is re-established when the device refreshes the token. For example, the SAS token expires every hour by default for C SDK, which can lead to regular disconnects. To learn more, see 401003 IoTHubUnauthorized error.

Some other possibilities include:

• The device lost underlying network connectivity longer than the MQTT keep-alive, resulting in a remote idle time-out. The MQTT keep-alive setting can be different per device.
• The device sent a TCP/IP-level reset but didn't send an application-level MQTT DISCONNECT. Basically, the device abruptly closed the underlying socket connection. Sometimes, bugs in older versions of the Azure IoT SDK might cause this issue.
• The device side application crashed.

Or, IoT Hub might be experiencing a transient issue. For more information, see 500xxx Internal errors.

To resolve this error:

• See the guidance for 401003 IoTHubUnauthorized error.
• Make sure the device has good connectivity to IoT Hub by testing the connection. If the network is unreliable or intermittent, we don't recommend increasing the keep-alive value because it could result in detection (via Azure Monitor alerts, for example) taking longer.
• Use the latest versions of the Azure IoT Hub SDKs.
• See the guidance for 500xxx Internal errors.

4043xx Configuration NotFound errors

You might see that your requests to IoT Hub fail with an error that begins with 4043. The following table lists the error codes, their descriptions, and possible solutions.

4044xx PnP NotFound errors

You might see that your requests to IoT Hub fail with an error that begins with 4044. The following table lists the error codes, their descriptions, and possible solutions.

405xxx MethodNotAllowed errors

You might see that your requests to IoT Hub fail with an error that begins with 405. The following table lists the error codes, their descriptions, and possible solutions.

4051xx Device model MethodNotAllowed errors

You might see that your requests to IoT Hub fail with an error that begins with 4051. The following table lists the error codes, their descriptions, and possible solutions.

409xxx Conflict errors

You might see that your requests to IoT Hub fail with an error that begins with 409. The following table lists the error codes, their descriptions, and possible solutions.

409001 DeviceAlreadyExists error

When trying to register a device in IoT Hub, you might see that the request fails with the error 409001 DeviceAlreadyExists.

This error occurs because there's already a device with the same device ID in the IoT hub.

To resolve this error, use a different device ID and try again.

409002 LinkCreationConflict error

You might see the error 409002 LinkCreationConflict in logs along with device disconnection or cloud-to-device message failure.

Generally, this error happens when IoT Hub detects a client has more than one connection. In fact, when a new connection request arrives for a device with an existing connection, IoT Hub closes the existing connection with this error.

In the most common case, a separate issue (such as 404104 DeviceConnectionClosedRemotely error) causes the device to disconnect. The device tries to reestablish the connection immediately, but IoT Hub still considers the device connected. IoT Hub closes the previous connection and logs this error.

Or, faulty device-side logic causes the device to establish the connection when one is already open.

To resolve this error, look for other errors in the logs that you can troubleshoot because this error usually appears as a side effect of a different, transient issue. Otherwise, make sure to issue a new connection request only if the connection drops.

4091xx Device model conflict errors

You might see that your requests to IoT Hub fail with an error that begins with 4091. The following table lists the error codes, their descriptions, and possible solutions.

4093xx Modules conflict errors

You might see that your requests to IoT Hub fail with an error that begins with 4093. The following table lists the error codes, their descriptions, and possible solutions.

4094xx Configuration conflict errors

You might see that your requests to IoT Hub fail with an error that begins with 4094. The following table lists the error codes, their descriptions, and possible solutions.

4095xx Digital twin conflict errors

You might see that your requests to IoT Hub fail with an error that begins with 4095. The following table lists the error codes, their descriptions, and possible solutions.

412xxx PreconditionFailed errors

You might see that your requests to IoT Hub fail with an error that begins with 412. The following table lists the error codes, their descriptions, and possible solutions.

412002 DeviceMessageLockLost error

When trying to send a cloud-to-device message, you might see that the request fails with the error 412002 DeviceMessageLockLost.

This error occurs because when a device receives a cloud-to-device message from the queue (for example, using ReceiveAsync()), IoT Hub locks the message for a lock time-out duration of one minute. If the device tries to complete the message after the lock time-out expires, IoT Hub throws this exception.

If IoT Hub doesn't get the notification within the one-minute lock time-out duration, it sets the message back to Enqueued state. The device can attempt to receive the message again. To prevent the error from happening in the future, implement device side logic to complete the message within one minute of receiving the message. This one-minute time-out can't be changed.

413xxx Request entity too large errors

You might see that your requests to IoT Hub fail with an error that begins with 413. The following table lists the error codes, their descriptions, and possible solutions.

415xxx Unsupported media type errors

You might see that your requests to IoT Hub fail with an error that begins with 415. The following table lists the error codes, their descriptions, and possible solutions.

429xxx Throttling exception errors

You might see that your requests to IoT Hub fail with an error that begins with 429. The following table lists the error codes, their descriptions, and possible solutions.

These errors occur when you exceed the throttling limits for the requested operation.

You can only monitor 429001 ThrottlingException error through Azure Monitor under the metric Number of Throttling Errors. Currently, the other throttling errors don't have an associated metric but are captured in the logs.

To resolve these errors, check if you're hitting the throttling limit by comparing your Telemetry message send attempts metric against the limits previously specified. You can also check the Number of throttling errors metric. For information about these metrics, see Device telemetry metrics. For information about how use metrics to help you monitor your IoT hub, see Monitor Azure IoT Hub.

IoT Hub returns 429001 ThrottlingException only after the limit is violated for too long a period. This delay is done so that your messages aren't dropped if your IoT hub gets burst traffic. In the meantime, IoT Hub processes the messages at the operation throttle rate, which might be slow if there's too much traffic in the backlog. For more information, see the Traffic shaping section of IoT Hub quotas and throttling.

Consider scaling up your IoT hub if you're running into quota or throttling limits.

499xxx Client closed request errors

You might see that your requests to IoT Hub fail with an error that begins with 499. The following table lists the error codes, their descriptions, and possible solutions.

500xxx Internal server errors

You might see that your requests to IoT Hub fail with an error that begins with 500 or mentions a server error. Some possibilities are:

There can be many causes for a 500xxx error response. In all cases, the issue is most likely transient. While the IoT Hub team works hard to maintain the SLA, small subsets of IoT Hub nodes can occasionally experience transient faults. When your device tries to connect to a node that's having issues, you receive this error.

To mitigate 5000xx errors, issue a retry from the device. To automatically manage retries, make sure you use the latest version of the Azure IoT Hub SDKs. For more information about best practices for transient fault handling and retries, see Transient fault handling.

If the problem persists, check Resource Health and Azure Status to see if IoT Hub has a known problem. You can also use the manual failover feature.

If there are no known problems and the issue continues, contact support for further investigation.

5003xx Resolution related errors

You might see that your requests to IoT Hub fail with an error that begins with 5003. The following table lists the error codes, their descriptions, and possible solutions.

5004xx MSI related errors

You might see that your requests to IoT Hub fail with an error that begins with 5004. The following table lists the error codes, their descriptions, and possible solutions.

5005xx PnP related errors

You might see that your requests to IoT Hub fail with an error that begins with 5005. The following table lists the error codes, their descriptions, and possible solutions.

502xxx Gateway related errors

You might see that your requests to IoT Hub fail with an error that begins with 502. The following table lists the error codes, their descriptions, and possible solutions.

503xxx Service unavailable related errors

You might see that your requests to IoT Hub fail with an error that begins with 503. The following table lists the error codes, their descriptions, and possible solutions.

5031xx Device model unavailable errors

You might see that your requests to IoT Hub fail with an error that begins with 5031. The following table lists the error codes, their descriptions, and possible solutions.

5032xx Configuration unavailable errors

You might see that your requests to IoT Hub fail with an error that begins with 5032. The following table lists the error codes, their descriptions, and possible solutions.

5033xx PnP unavailable related errors

You might see that your requests to IoT Hub fail with an error that begins with 5033. The following table lists the error codes, their descriptions, and possible solutions.

504xxx Gateway timeout related errors

You might see that your requests to IoT Hub fail with an error that begins with 504. The following table lists the error codes, their descriptions, and possible solutions.

504101 GatewayTimeout error

When trying to invoke a direct method from IoT Hub to a device, you might see that the request fails with the error 504101 GatewayTimeout.

This error occurs because IoT Hub encountered an error and couldn't confirm if the direct method completed before timing out. Or, when using an earlier version of the Azure IoT C# SDK (<1.19.0), the AMQP link between the device and IoT Hub can be dropped silently because of a bug.

To resolve this error, issue a retry or upgrade to the latest version of the Azure IOT C# SDK.

Related content

• Troubleshoot Azure IoT Hub Device Provisioning Service
• Monitor, diagnose, and troubleshoot device connectivity
• IoT Hub quotas and throttling
• Monitor Azure IoT Hub