MQTT response status codes

Devices built with the nRF Cloud library (subsys/net/lib/nrf_cloud in the nRF Connect SDK) can receive error information from a few distinct sources over MQTT, each delivered to the application through a different handler:

• nRF Cloud API status codes: reported through enum nrf_cloud_error, populated from the numeric error code in the JSON payload the backend returns.
• MQTT return codes: reported through enum nrf_cloud_error_status, populated from the raw MQTT CONNACK or SUBACK return code the broker sends.

note

Most of the error codes documented on this page are not expected to occur under normal operation. Encountering one of them, other than the codes explicitly marked as rate limits or transient, usually indicates the device was incorrectly provisioned.

nRF Cloud API status codes

Status code	NCS enum constant (enum nrf_cloud_error)	Description	Retry behavior
-1	NRF_CLOUD_ERROR_UNKNOWN	No error code was present in the response, or the response could not be parsed.	Retry once. Otherwise, do not retry.
0	NRF_CLOUD_ERROR_NONE	No error.	Do not retry.
40000	NRF_CLOUD_ERROR_BAD_REQUEST	Returned for malformed or invalid request data (such as an invalid Team ID) or a failed precondition (e.g. a resource in the wrong state or a limit exceeded).	Retry with exponential backoff.
40001	NRF_CLOUD_ERROR_INVALID_CERT	Device does not have a valid device certificate for associating (adding) it to the account.	Do not retry. Retrying resends the same invalid certificate.
40002	NRF_CLOUD_ERROR_DISSOCIATE	Device cannot be dissociated (removed from the account) because it was added through legacy pairing instead of the AssociateDevice endpoint.	Do not retry. The device's association record was created through the legacy path, and the dissociate logic only knows how to remove associations created through AssociateDevice, so the request is rejected outright.
40005	N/A	Usage limit exceeded: the monthly quota on the free Developer plan was exceeded.	Do not retry until the next billing cycle.
40100	NRF_CLOUD_ERROR_ACCESS_DENIED	Access denied: the caller does not have access to the requested resource.	Do not retry.
40101	NRF_CLOUD_ERROR_DEV_ID_IN_USE	Device is already associated with another account.	Do not retry.
40102	NRF_CLOUD_ERROR_INVALID_OWNER_CODE	Invalid ownership code (PIN or HWID) supplied when associating a device.	Do not retry.
40103	NRF_CLOUD_ERROR_DEV_NOT_ASSOCIATED	Device is not associated with the calling account.	Do not retry.
40410	NRF_CLOUD_ERROR_DATA_NOT_FOUND	Requested data was not found.	Do not retry.
40411	NRF_CLOUD_ERROR_NRF_DEV_NOT_FOUND	Device was not found, for example because it is not provisioned or was already deleted.	Do not retry.
40412	NRF_CLOUD_ERROR_NO_DEV_NOT_PROV	Device is not provisioned.	Do not retry.
40413	NRF_CLOUD_ERROR_NO_DEV_DISSOCIATE	Device could not be dissociated.	Retry once. Otherwise, do not retry.
40414	NRF_CLOUD_ERROR_NO_DEV_DELETE	Device could not be deleted.	Retry once. Otherwise, do not retry.
40420	N/A	Resource not found: a generic code returned when a device, certificate, or API key is not found by ID.	Do not retry.
40499	NRF_CLOUD_ERROR_NOT_FOUND_NO_ERROR	Item not found. This is not actually an error. The requested item simply does not exist. It is explicitly excluded from failure handling in nrf_cloud_rest.c.	Not applicable.
41600	NRF_CLOUD_ERROR_BAD_RANGE	Range not satisfiable: a malformed or out-of-bounds Range header on a ranged request.	Do not retry.
42200	NRF_CLOUD_ERROR_VALIDATION	Validation failed: invalid request data.	Do not retry.
50010	NRF_CLOUD_ERROR_INTERNAL_SERVER	Internal server error. This error should not occur. If you see it, contact us.	Retry with exponential backoff, up to the retry limit described in Retries with exponential backoff .

MQTT return codes

MQTT return code	NCS enum constant (enum nrf_cloud_error_status)	Meaning and typical root cause	Retry behavior
CONNACK 0x00 MQTT_CONNECTION_ACCEPTED	NRF_CLOUD_ERR_STATUS_NONE	Connection accepted.	Do not retry.
CONNACK 0x01 MQTT_UNACCEPTABLE_PROTOCOL_VERSION	NRF_CLOUD_ERR_STATUS_MQTT_CONN_BAD_PROT_VER	The MQTT protocol version requested by the client is not supported by the broker. Typically a firmware version mismatch.	Do not retry.
CONNACK 0x02 MQTT_IDENTIFIER_REJECTED	NRF_CLOUD_ERR_STATUS_MQTT_CONN_ID_REJECTED	Client identifier rejected. Commonly a device ID or certificate mismatch. See the onboarding troubleshooting notes for cases where the firmware client ID does not match the ID the device was onboarded with.	Do not retry.
CONNACK 0x03 MQTT_SERVER_UNAVAILABLE	NRF_CLOUD_ERR_STATUS_MQTT_CONN_SERVER_UNAVAIL	The broker is temporarily unavailable.	Retry with exponential backoff.
CONNACK 0x04 MQTT_BAD_USER_NAME_OR_PASSWORD	NRF_CLOUD_ERR_STATUS_MQTT_CONN_BAD_USR_PWD	Malformed username or password. Device MQTT authentication normally uses mutual TLS rather than a username and password, so this is unusual for firmware devices.	Do not retry.
CONNACK 0x05 MQTT_NOT_AUTHORIZED	NRF_CLOUD_ERR_STATUS_MQTT_CONN_NOT_AUTH	Client not authorized to connect. The device's IoT policy denies iot:Connect, typically because the AWS IoT Thing is not attached or associated (the iot:Connection.Thing.IsAttached condition fails), or the certificate is inactive or detached.	Do not retry.
Any other or unrecognized CONNACK return code (the default case of translate_mqtt_connack_result())	NRF_CLOUD_ERR_STATUS_MQTT_CONN_FAIL	Generic connection failure that does not match a known CONNACK code. This should not occur. If you see it, contact us.	Retry with exponential backoff.
SUBACK 0x80 MQTT_SUBACK_FAILURE, or any unrecognized SUBACK code	NRF_CLOUD_ERR_STATUS_MQTT_SUB_FAIL	Topic subscription failed. The device's IoT policy does not grant iot:Subscribe on the requested topic filter (subscriptions are scoped per-device).	Do not retry.
N/A	NRF_CLOUD_ERR_STATUS_AGNSS_PROC	Not broker-derived. Set locally in agnss_process() ( nrf_cloud_fsm.c). Rate limit of A-GNSS location service requests.	Do not retry.
N/A	NRF_CLOUD_ERR_STATUS_PGPS_PROC	Not broker-derived. Set locally in pgps_process() ( nrf_cloud_fsm.c). Rate limit of P-GPS location service requests.	Do not retry.

Retries with exponential backoff

For codes identified for retry with exponential backoff in the preceding tables, retry up to five times with an exponential backoff of $2^{3n}$ seconds between attempts (where $n$ is the retry number). An example retry strategy follows.

Retry attempt	Wait time (seconds)
1	8
2	64
3	512
4	4096
5	32,768