Response Codes

Reference·Audience: MQTT API integrators·Use: look up any command response.code — its meaning, cause, recommended fix, and which commands return it

Overview

Every reply to a command carries a response object with a numeric code and a human-readable description. This page lists every code: what it means, why it occurs, what to do, and which commands can return it.

code is a closed set. Only the values in the catalog are defined, so treat any other value as an unrecognized reply and log it.

Response codes come only from the reader, inside a command reply. They are separate from the return codes that MQTT 3.1.1 defines for CONNACK and SUBACK, and from errors that your MQTT client library raises. Events never carry a response code.

The catalog and the matrix are generated from the MQTT API contract.

The Response Object

Example

Response object

{

"code": 0,

"description": "Success"

}

Schema

Response object

* required— not applicableColored badge = JSON type

#	Field	Type	Enum / Units	Example	Description
1	code*	integer	0–101	0	Response codes: | Code | Meaning | | --- | --- | | 0 | Success | | 1 | Command payload is accepted | | 2 | Invalid payload | | 3 | Not able to retrieve information | | 4 | Firmware update in progress | | 5 | Can't reboot device, inventory in progress | | 6 | Region is not configured | | 7 | Interface is not available | | 8 | Insufficient flash size | | 9 | File not found | | 10 | Configuration already exists | | 11 | Inventory in progress | | 12 | No Radio Operation in Progress | | 13 | Firmware update Failed | | 14 | Battery is low, Cannot update firmware | | 15 | WIFI Error - SSID not found | | 16 | WIFI Error - Cannot delete active SSID | | 17 | WIFI Error - SSID missed | | 18 | WIFI Error - SSID already exist | | 19 | WIFI Error - SSID count overflow | | 20 | Wifi is not supported | | 21 | Certificate not found | | 22 | Advanced configuration not set | | 23 | Invalid enum value | | 24 | Max 32 prefilters limit exceeded | | 25 | Max 3 publish topics exceeded | | 26 | Max 1 subscribe topic exceeded | | 27 | Invalid tenant ID length | | 28 | Tag match pattern length exceeded | | 29 | Url missing for HTTP source | | 30 | Certificate content missing for direct source | | 31 | Max write length exceeded | | 32 | Write data length mismatch | | 33 | Endpoint already configured | | 34 | Certificate base64 decode failed | | 35 | Can't modify an active endpoint | | 36 | Missing client key or client certificate | | 37 | Invalid verification type for MQTT TLS | | 101 | Default error |
2	description*	string	—	Success	response description in detail

How to Read a Code

Decide the outcome from response in this order:

• code is 0, or code is absent and description is "Success": the command succeeded. The contract requires code, but readers have been reported to omit it on a successful reply; error replies always include it. See Success Without a Code.
• code is 1: the reader accepted the request and is still working on it. Only set_os, reboot, and install_certificate return it. See Asynchronous Commands.
• code is 101: a default error, returned when no more specific code applies.
• Any other code: the command did not succeed. Use the code's cause and recommended action in the catalog.

Don't parse description: its wording can change between firmware builds.

The catalog gives each code its cause and recommended action. When the fix takes more than one step, these guides walk through it:

Codes	Where the fix is
10, 25, 26, 27, 33, 35, 37 (endpoint configuration)	Endpoint Configuration and Recover from Configuration Problems
15 to 20 (Wi-Fi profiles)	Network Configuration
9, 21, 29, 30, 34, 36 (certificates)	Certificate Management
4, 8, 13, 14 (firmware updates)	Device Lifecycle and Recover from Firmware Problems
5, 11, 12, 22, 24, 28 (inventory and radio settings)	Configure Advanced Radio Settings
31, 32 (tag writes)	Read and Write Tag Memory
No reply at all	Commands Get No Response

To decide in code what to do with a reply, including when to retry, see Message Envelopes and Correlation and Duplicates and Retries.

Before you retry after an error, apply the contract's rule: retry only when the recommended action names a condition that can change without changing your request, such as waiting, stopping an inventory, or charging the reader. Otherwise change the request first. See Duplicates and Retries.

Response Code Catalog

Every code in ascending order, with 101 last. Kind follows from the code: 0 is success, 1 is an asynchronous acceptance, 101 is the catch-all, and every other code is an error. Applies to lists the commands in this reference that can return the code.

Code	Kind	Meaning	IoT status code	Cause	Recommended action	Applies to
0	Success	Success	IOT_STATUS_SUCCESS	Command executed successfully	No action required	All commands
1	Accepted (async)	Command payload is accepted	IOT_STATUS_CMD_PAYLOAD_ACCEPTED	The device accepted the payload and is processing it asynchronously	Wait for a follow-up event or poll status to confirm completion	set_os, reboot, install_certificate
2	Error	Invalid payload	IOT_ERROR_INVALID_PAYLOAD	The JSON payload is malformed or contains invalid field values	Validate the payload against the command schema and correct any errors	set_wifi, delete_wifi_profile
3	Error	Not able to retrieve information	IOT_ERROR_INFO_NOT_AVAILABLE	The device could not gather the requested information at this time	Retry the command after a short delay; if persistent, reboot the device	get_status, get_endpoint_config, get_wifi, get_eth, get_current_region, get_installed_certificates, get_operating_mode, get_post_filter
4	Error	Firmware update in progress	IOT_STATUS_FW_UPDATE_IN_PROGRESS	A firmware update is already running on the device	Wait for the current update to complete before sending another set_os command	set_os
5	Error	Can't reboot device, inventory in progress	IOT_ERROR_IN_REBOOT_INVENTORY_IN_PROGRESS	An RFID inventory operation is currently active	Stop the inventory with control_operation before rebooting	reboot
6	Error	Region is not configured	IOT_STATUS_REGION_NOT_CONFIGURED	No regulatory region has been set on the device	Configure the region before attempting to connect	cloud_connect
7	Error	Interface is not available	IOT_ERROR_INTERFACE_NOT_AVAILABLE	The requested network interface is not present or not enabled	Verify the device has the required network interface and that it is enabled	cloud_connect
8	Error	Insufficient flash size	IOT_ERROR_LOW_FLASH_SIZE	Not enough free flash storage to download the firmware file	Free up flash space or use a smaller firmware package	set_os
9	Error	File not found	IOT_STATUS_FILE_NOT_FOUND	The specified file or certificate could not be found on the device or server	Verify the file path or URL is correct and the file exists	install_certificate, delete_certificate, get_installed_certificates, set_os
10	Error	Configuration already exists	IOT_ERROR_CONFIG_ALREADY_EXIST	An endpoint or configuration with the same name already exists	Delete the existing configuration first or use a different name	config_endpoint
11	Error	Inventory in progress	IOT_ERROR_INVENTORY_IN_PROGRESS	An RFID inventory operation is currently running	Stop the current inventory before starting a new operation or changing the mode	control_operation, set_operating_mode
12	Error	No Radio Operation in Progress	IOT_ERROR_NO_RADIO_OP_IN_PROGRESS	A stop command was sent but no radio operation is currently active	No action required — the radio is already idle	control_operation
13	Error	Firmware update Failed	IOT_ERROR_FW_UPDATE_FAIL	The firmware download or installation failed	Check the firmware URL, network connectivity, and retry the update	set_os
14	Error	Battery is low, Cannot update firmware	IOT_ERROR_FW_UPDATE_FAIL_LOW_BATTERY	Battery charge is too low to safely perform a firmware update	Charge the device or connect to external power before retrying	set_os
15	Error	WIFI Error - SSID not found	IOT_ERROR_SSID_NOT_FOUND	The specified Wi-Fi SSID does not exist in saved profiles	Verify the SSID name is correct and that the profile has been saved	set_wifi, delete_wifi_profile
16	Error	WIFI Error - Cannot delete active SSID	IOT_ERROR_DELETE_ACTIVE_SSID	The Wi-Fi profile being deleted is the currently connected network	Disconnect from the network or connect to a different SSID before deleting	delete_wifi_profile
17	Error	WIFI Error - SSID missed	IOT_ERROR_SSID_MISSED	The required SSID field is missing from the payload	Include the SSID field in the command payload	set_wifi, delete_wifi_profile
18	Error	WIFI Error - SSID already exist	IOT_ERROR_SSID_ALREADY_EXIST	A Wi-Fi profile with this SSID is already saved on the device	Delete the existing profile first or update it instead of creating a new one	set_wifi
19	Error	WIFI Error - SSID count overflow	IOT_ERROR_SSID_LIMIT_OVERFLOW	The maximum number of saved Wi-Fi profiles has been reached	Delete an unused Wi-Fi profile before adding a new one	set_wifi
20	Error	Wifi is not supported	IOT_ERROR_WIFI_INTER_NOT_SUPPORTED	The device hardware does not have a Wi-Fi interface	Use Ethernet or another supported interface for network connectivity	set_wifi
21	Error	Certificate not found	IOT_ERROR_CERT_NOT_FOUND	The specified certificate is not installed on the device	Verify the certificate name and install it using install_certificate if needed	delete_certificate, get_installed_certificates, install_certificate
22	Error	Advanced configuration not set	IOT_CTRL_ADVANCED_PROFILE_NOT_SET	The operating mode requires an advanced profile that has not been configured	Configure the advanced profile settings before setting the operating mode	set_operating_mode
23	Error	Invalid enum value	IOT_ERROR_INVALID_ENUM	A field value does not match any of the allowed enum options	Check the schema for allowed values and correct the field	config_endpoint, set_wifi, install_certificate, control_operation, set_operating_mode, set_post_filter
24	Error	Max 32 prefilters limit exceeded	IOT_ERROR_PREFILTERS_LIMIT_EXCEEDED	More than 32 prefilter rules were specified	Reduce the number of prefilter rules to 32 or fewer	set_operating_mode
25	Error	Max 3 publish topics exceeded	IOT_ERROR_PUBLISH_TOPICS_EXCEEDED	More than 3 publish topics were specified in the endpoint configuration	Reduce the number of publish topics to 3 or fewer	config_endpoint
26	Error	Max 1 subscribe topic exceeded	IOT_ERROR_SUBSCRIBE_TOPIC_EXCEEDED	More than 1 subscribe topic was specified in the endpoint configuration	Use only 1 subscribe topic per endpoint	config_endpoint
27	Error	Invalid tenant ID length	IOT_ERROR_INVALID_TENANTID_LENGTH	The tenant ID exceeds the maximum allowed character length	Shorten the tenant ID to within the allowed limit	config_endpoint
28	Error	Tag match pattern length exceeded	IOT_ERROR_TAG_MATCH_PATTERN_LENGTH_EXCEEDED	The tag match pattern string exceeds the maximum allowed length	Shorten the tag match pattern to within the allowed limit	set_operating_mode
29	Error	Url missing for HTTP source	IOT_ERROR_URL_MISSING	The URL for the HTTP source is missing	Provide a valid URL for the HTTP source	install_certificate
30	Error	Certificate content missing for direct source	IOT_ERROR_CERT_CONTENT_MISSING	The certificate content is missing for the direct source	Provide the required certificate content for the direct source	install_certificate
31	Error	Max write length exceeded	IOT_ERROR_MAX_WRITE_LENGTH_EXCEEDED	The maximum write length for the certificate has been exceeded	Ensure the certificate size is within the allowed limit.	set_operating_mode
32	Error	Write data length mismatch	IOT_ERROR_WRITE_DATA_LENGTH_MISMATCH	The length of the data being written does not match the expected length	Ensure the data length matches the length value added on payload if field given.	set_operating_mode
33	Error	Endpoint already configured	IOT_ERROR_ENDPOINT_ALREADY_CONFIGURED	An endpoint with the same configuration already exists on the device	Delete the existing endpoint configuration first or modify it instead of creating a new one	config_endpoint
34	Error	Certificate base64 decode failed	IOT_ERROR_CERT_BASE64_DECODE_FAILED	The base64 encoded certificate content could not be decoded	Ensure the certificate content is correctly base64 encoded and try again	install_certificate
35	Error	Can't modify an active endpoint	IOT_ERROR_CANT_MODIFY_ACTIVE_ENDPOINT	An attempt was made to modify an endpoint that is currently active	Deactivate the endpoint before making modifications	config_endpoint
36	Error	Missing client key or client certificate	IOT_MISSING_CLIENT_KEY_OR_CERT	When client certificate and its client key are not sent together for installation	Always install client certificate with its key	install_certificate
37	Error	Invalid verification type for MQTT TLS	IOT_INVALID_MQTT_TLS_VERIFICATION_TYPE	The verification type specified for MQTT TLS is can't be NONE	Specify a valid verification type for MQTT TLS such as verify host, verify peer or verify host and peer	config_endpoint
101	Catch-all	Default error	—	This is an error code for unknown or unhandled errors. It is a catch-all for any error that does not have a specific code assigned.	Investigate the error and take appropriate action based on the context.	All commands

Codes by Command

The codes each command can return. Every command can also return 0 and 101, which are included in each row.

Command	Response codes
get_version	0 · 101
get_status	0 · 3 · 101
get_current_region	0 · 3 · 101
get_eth	0 · 3 · 101
get_wifi	0 · 3 · 101
set_wifi	0 · 2 · 15 · 17 · 18 · 19 · 20 · 23 · 101
delete_wifi_profile	0 · 2 · 15 · 16 · 17 · 101
get_endpoint_config	0 · 3 · 101
config_endpoint	0 · 10 · 23 · 25 · 26 · 27 · 33 · 35 · 37 · 101
get_installed_certificates	0 · 3 · 9 · 21 · 101
install_certificate	0 · 1 · 9 · 21 · 23 · 29 · 30 · 34 · 36 · 101
delete_certificate	0 · 9 · 21 · 101
config_events	0 · 101
set_os	0 · 1 · 4 · 8 · 9 · 13 · 14 · 101
reboot	0 · 1 · 5 · 101
get_operating_mode	0 · 3 · 101
set_operating_mode	0 · 11 · 22 · 23 · 24 · 28 · 31 · 32 · 101
get_post_filter	0 · 3 · 101
set_post_filter	0 · 23 · 101
control_operation	0 · 11 · 12 · 23 · 101

Notes and Caveats

• Codes 6 and 7 are defined but no published command returns them. They are kept because response codes are a fixed numeric sequence, and removing one would renumber the rest.
• Codes 31 and 32 concern tag write length in set_operating_mode. The cause text for code 31 mentions a certificate, which does not fit a tag write; go by the code's name.
• A command with no row-specific codes, such as get_version or config_events, returns only 0 and 101.
• A reply with code 1 is not a result. Subscribe to the event topic before you send set_os or install_certificate, and wait for the outcome. reboot sends no outcome event.
• No reply is not a code. A misspelled command value, an oversized message, or a full command queue can produce no reply at all. See What Happens to a Malformed Command.