Last month we deployed a change to Adafruit IO’s MQTT broker that allowed us to rate limit connection attempts. Although we don’t like to throttle or ban users, the change was necessary to protect Adafruit IO from abuse, and ensure the overall health of the service.

This presented a problem: How do we inform users when they have been throttled or banned? Ideally the MQTT protocol would allow for us to inform the user using a standard response, but currently the connection acknowledgement packet (CONNACK) has a limited set of response codes.

The MQTT v3.1.1 protocol has the following values defined for the CONNACK packet response code:

Value

Return Code Response

Description

0

0x00 Connection Accepted

Connection accepted

1

0x01 Connection Refused, unacceptable protocol version

The Server does not support the level of the MQTT protocol requested by the Client

2

0x02 Connection Refused, identifier rejected

The Client identifier is correct UTF-8 but not allowed by the Server

3

0x03 Connection Refused, Server unavailable

The Network Connection has been made but the MQTT service is unavailable

4

0x04 Connection Refused, bad user name or password

The data in the user name or password is malformed

5

0x05 Connection Refused, not authorized

The Client is not authorized to connect

6-255

 

Reserved for future use

The current set of codes didn’t allow us to clearly communicate the reason for disconnects to our users. We have extended the list of codes in the CONNACK packet to include connection throttle (0x06) and ban (0x07).

Value

Return Code Response

Description

6

0x06 Connection Refused, throttled

Client has exceeded connection rate limit. Please try again later.

7

0x07 Connection Refused, banned

The client has been banned by the server administrator.

We have submitted these two new codes to the OASIS MQTT Technical Committee for comment, and we are adding support to our MQTT client libraries. If you would like to comment on these changes, please visit our IO forum and share your thoughts.