Reason codes MQTT 5 : table de référence complète avec causes et solutions

Les reason codes MQTT sont les valeurs d'état sur un octet que les brokers et clients MQTT 5 placent dans les acquittements et les paquets DISCONNECT pour indiquer précisément ce qui s'est passé. Cette référence répertorie chaque code, les paquets qui peuvent le porter, ce qui le déclenche généralement et comment y remédier, pour transformer un 0x87 ou un 0x97 énigmatique dans vos journaux en action concrète.

Comment fonctionnent les reason codes MQTT

MQTT 3.1.1 ne comptait qu'une poignée de valeurs d'état : six return codes dans le CONNACK et une seule valeur d'échec (0x80) dans le SUBACK. Tout le reste, comme une publication rejetée ou une déconnexion côté broker, était silencieux : la connexion se fermait simplement. MQTT 5 a remplacé cela par un ensemble commun de reason codes utilisé dans CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP, SUBACK, UNSUBACK, DISCONNECT et AUTH. C'est l'une des fonctionnalités de MQTT 5 les plus utiles pour quiconque exploite des appareils sur le terrain.

Deux règles rendent la table facile à lire :

• Les valeurs inférieures à 0x80 signifient un succès ou un résultat qui n'est pas une erreur, comme « QoS 1 accordée » ou « aucun subscriber correspondant ».
• Les valeurs de 0x80 et plus signifient un échec. Le paquet qui porte le code indique quelle opération a échoué.

De nombreux paquets peuvent aussi porter une propriété Reason String, une explication lisible fournie par l'émetteur. Journalisez-la toujours lorsqu'elle est présente : elle contient souvent la limite exacte qui a été atteinte.

Codes de succès et d'information

Un SUBACK qui accorde une QoS inférieure à celle demandée n'est pas une erreur. Si vous demandez la QoS 2 et obtenez 0x01, la QoS maximum du broker est 1 pour votre connexion, et les messages arriveront au plus en QoS 1.

Référence des reason codes d'erreur

Notez que certains codes, comme 0x8D et 0x8E, n'apparaissent que dans un DISCONNECT envoyé par le broker. D'autres, comme 0x84 à 0x88, ne peuvent apparaître que dans un CONNACK, car ils décrivent pourquoi la connexion a été refusée d'emblée.

Correspondance entre return codes MQTT 3.1.1 et MQTT 5

Si vous prenez en charge les deux versions du protocole, cette correspondance garde votre gestion d'erreurs cohérente. L'explication détaillée se trouve dans le guide des return codes CONNACK MQTT.

Journaliser les reason codes MQTT en Python

Avec paho-mqtt 2.x et CallbackAPIVersion.VERSION2, chaque callback reçoit un objet ReasonCode. Sa forme textuelle est le nom défini par la spécification et .value est le code numérique, exactement ce qu'il vous faut dans les journaux :

import paho.mqtt.client as mqtt

def on_connect(client, userdata, flags, reason_code, properties):
    print(f"CONNACK: {reason_code} (0x{reason_code.value:02X})")
    if reason_code.is_failure:
        return
    client.subscribe("connectmq/demo/b7d2/#", qos=2)

def on_subscribe(client, userdata, mid, reason_code_list, properties):
    for rc in reason_code_list:
        print(f"SUBACK: {rc} (0x{rc.value:02X})")

def on_disconnect(client, userdata, flags, reason_code, properties):
    reason = getattr(properties, "ReasonString", None) if properties else None
    print(f"DISCONNECT: {reason_code} (0x{reason_code.value:02X}) {reason or ''}")

client = mqtt.Client(
    mqtt.CallbackAPIVersion.VERSION2,
    client_id="reason-demo-b7d2",
    protocol=mqtt.MQTTv5,
)
client.on_connect = on_connect
client.on_subscribe = on_subscribe
client.on_disconnect = on_disconnect
client.connect("broker.connectmq.com", 1883, keepalive=30)
client.loop_forever()

Exécutez-le contre le serveur MQTT public gratuit, réservé aux tests et jamais aux données de production, et vous verrez Success à la connexion et une QoS accordée dans le SUBACK. Essayez de vous abonner à un filtre invalide comme connectmq/demo/b7d2/#/x pour voir 0x8F Topic Filter invalid en action. Avec MQTT.js, les mêmes informations se trouvent dans connack.reasonCode, dans le tableau granted du callback d'abonnement et dans le paquet de l'événement disconnect.

Méthode de débogage par reason code

Un ordre pratique pour analyser un échec :

1. Identifiez le paquet. Un code dans un CONNACK signale un problème de connexion ; dans un SUBACK, un problème d'abonnement ; dans un DISCONNECT, un problème en cours d'exécution.
2. Lisez la Reason String. Elle ramène généralement la cause à une limite ou une règle précise.
3. Vérifiez d'abord les identifiants et l'identité pour 0x85, 0x86 et 0x87. Le guide pour corriger l'erreur MQTT connection refused: not authorized traite ce sujet en profondeur.
4. Vérifiez les limites pour 0x93, 0x95, 0x96 et 0x97 : taille des messages, débit, nombre de connexions et messages en vol.
5. Vérifiez l'hygiène de la flotte pour 0x8E : les client ID en double sont la cause la plus fréquente des boucles de déconnexion.

Les reason codes sur ConnectMQ

ConnectMQ prend en charge MQTT 3.1.1 et 5.0 : les clients MQTT 5 reçoivent donc les reason codes ci-dessus. Les quotas des offres se manifestent sous la forme 0x97 Quota exceeded, par exemple lorsqu'un broker Serverless (Free) a déjà atteint son maximum de 25 connexions. Les fonctionnalités de l'offre comptent aussi : l'offre gratuite accorde la QoS jusqu'à 1, si bien qu'un abonnement en QoS 2 est accordé à une QoS inférieure dans le SUBACK, tandis que la QoS 2 et les shared subscriptions sont incluses dans l'offre Serverless (Paid). Les échecs de connexion répétés sont considérés comme suspects et l'IP source peut être bloquée : ne laissez donc jamais un client réessayer de mauvais identifiants en boucle serrée.

Pour comprendre ce que fait un broker MQTT de ces codes, ou voir le protocole complet dans son contexte, consultez le tutoriel MQTT.

Déboguer plus vite avec ConnectMQ

Un broker MQTT managé doté d'un client intégré au navigateur et d'un explorateur de topics en direct permet de reproduire beaucoup plus vite une publication ou un abonnement en échec. Créez un broker Serverless (Free) sur app.connectmq.com, sans carte bancaire, et testez votre gestion d'erreurs face à de vraies réponses MQTT 5.

Questions fréquentes

Quelle est la différence entre un reason code et un return code ?

Return code est le terme MQTT 3.1.1 désignant les six valeurs du CONNACK. MQTT 5 a généralisé l'idée sous la forme de reason codes présents dans presque tous les acquittements et dans le DISCONNECT.

Quels reason codes signifient un succès ?

Toute valeur inférieure à 0x80. Cela comprend 0x00 Success, 0x01 et 0x02 pour la QoS accordée, ainsi que des valeurs informatives comme 0x10 No matching subscribers.

Que signifie le reason code MQTT 0x97 ?

0x97 correspond à Quota exceeded : le client a atteint une limite, comme le nombre maximum de connexions ou une restriction de l'offre. Réduisez l'usage ou passez à une offre aux limites plus élevées.

Les clients MQTT 3.1.1 reçoivent-ils les reason codes MQTT 5 ?

Non. Une connexion 3.1.1 ne reçoit que les return codes CONNACK classiques et la valeur d'échec 0x80 du SUBACK. Connectez-vous avec la version 5 du protocole pour recevoir des reason codes détaillés.