Códigos de motivo de MQTT 5 (reason codes): tabla de referencia completa con causas y soluciones

Los códigos de motivo de MQTT (reason codes) son los valores de estado de un solo byte que los brokers y clientes MQTT 5 incluyen en los acuses de recibo y en los paquetes DISCONNECT para indicar exactamente qué ha ocurrido. Esta referencia recoge todos los códigos, qué paquetes pueden transportarlos, qué suele provocarlos y cómo resolverlos, para que puedas convertir un críptico 0x87 o 0x97 en tus registros en un siguiente paso concreto.

Cómo funcionan los códigos de motivo de MQTT

MQTT 3.1.1 solo tenía un puñado de valores de estado: seis códigos de retorno de CONNACK y un único valor de fallo (0x80) en SUBACK. Todo lo demás, como una publicación rechazada o una desconexión iniciada por el broker, era silencioso; la conexión simplemente se cerraba. MQTT 5 lo sustituyó por un conjunto compartido de reason codes que se usa en CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP, SUBACK, UNSUBACK, DISCONNECT y AUTH. Es una de las funciones de MQTT 5 más prácticas para cualquiera que opere dispositivos en campo.

Dos reglas facilitan la lectura de la tabla:

• Los valores por debajo de 0x80 indican éxito o un resultado que no es un error, como "QoS 1 concedido" o "no hay suscriptores coincidentes".
• Los valores de 0x80 en adelante indican fallo. El paquete que transporta el código te dice qué operación ha fallado.

Muchos paquetes también pueden llevar una propiedad Reason String, una explicación legible del emisor. Regístrala siempre que aparezca; a menudo contiene el límite exacto que se ha alcanzado.

Códigos de éxito e informativos

Un SUBACK que concede un QoS inferior al solicitado no es un error. Si pides QoS 2 y recibes 0x01, el QoS máximo del broker para tu conexión es 1, y los mensajes llegarán como mucho con QoS 1.

Referencia de códigos de error

Ten en cuenta que algunos códigos, como 0x8D y 0x8E, solo aparecen en un DISCONNECT enviado por el broker. Otros, como los de 0x84 a 0x88, solo pueden aparecer en CONNACK, porque describen por qué se rechazó la conexión desde el principio.

Equivalencia entre los códigos de retorno de MQTT 3.1.1 y MQTT 5

Si admites ambas versiones del protocolo, esta equivalencia mantiene coherente tu gestión de errores. La explicación detallada está en la guía de códigos de retorno CONNACK de MQTT.

Registrar los códigos de motivo MQTT en Python

Con paho-mqtt 2.x y CallbackAPIVersion.VERSION2, cada callback recibe un objeto ReasonCode. Su forma de cadena es el nombre de la especificación y .value es el código numérico, justo lo que quieres en los registros:

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()

Ejecútalo contra el servidor MQTT público gratuito de broker.connectmq.com (pensado para pruebas y prototipos, no para datos de producción) y verás Success al conectar y un QoS concedido en el SUBACK. Prueba a suscribirte a un filtro no válido como connectmq/demo/b7d2/#/x para ver 0x8F Topic Filter invalid en acción. Con MQTT.js, la misma información está en connack.reasonCode, en el array granted del callback de suscripción y en el paquete del evento disconnect.

Flujo de depuración según el código de motivo

Un orden práctico para investigar un fallo:

1. Identifica el paquete. Un código en CONNACK es un problema de conexión; en SUBACK, un problema de suscripción; en DISCONNECT, un problema en tiempo de ejecución.
2. Lee la Reason String. Normalmente reduce la causa a un límite o una regla concretos.
3. Comprueba primero las credenciales y la identidad para 0x85, 0x86 y 0x87. La guía para resolver MQTT connection refused: not authorized lo trata en profundidad.
4. Comprueba los límites para 0x93, 0x95, 0x96 y 0x97: tamaño de mensaje, ritmo, número de conexiones y mensajes en vuelo.
5. Comprueba la higiene de la flota para 0x8E: los client ID duplicados son la causa más habitual de los bucles de desconexión.

Códigos de motivo en ConnectMQ

ConnectMQ admite MQTT 3.1.1 y 5.0, así que los clientes MQTT 5 reciben los reason codes anteriores. Las cuotas del plan aparecen como 0x97 Quota exceeded, por ejemplo cuando un broker Serverless gratuito ya tiene su máximo de 25 conexiones. Las funciones del plan también importan: el plan gratuito concede QoS hasta 1, así que una suscripción con QoS 2 se concede con un QoS inferior en el SUBACK, mientras que QoS 2 y las suscripciones compartidas llegan con el plan Serverless de pago. Los inicios de sesión fallidos repetidos se tratan como sospechosos y la IP de origen puede bloquearse, así que nunca dejes un cliente reintentando con credenciales erróneas en un bucle cerrado.

Para saber más sobre qué hace un broker MQTT con estos códigos, o ver el protocolo completo en contexto, consulta el tutorial de MQTT.

Depura más rápido con ConnectMQ

Un broker MQTT gestionado con cliente en el navegador y explorador de topics en directo hace mucho más rápido reproducir una publicación o suscripción que falla. Crea un broker Serverless gratuito en app.connectmq.com, sin tarjeta de crédito, y prueba tu gestión de errores con respuestas reales de MQTT 5.

Preguntas frecuentes

¿Qué diferencia hay entre un código de motivo y un código de retorno?

Código de retorno (return code) es el término de MQTT 3.1.1 para los seis valores de CONNACK. MQTT 5 generalizó la idea en códigos de motivo (reason codes) que aparecen en casi todos los acuses de recibo y en DISCONNECT.

¿Qué códigos de motivo indican éxito?

Cualquier valor por debajo de 0x80. Eso incluye 0x00 Success, 0x01 y 0x02 para el QoS concedido y valores informativos como 0x10 No matching subscribers.

¿Qué significa el código de motivo MQTT 0x97?

0x97 es Quota exceeded: el cliente alcanzó un límite, como el máximo de conexiones o una restricción del plan. Reduce el uso o pásate a un plan con límites más altos.

¿Reciben los clientes MQTT 3.1.1 los códigos de motivo de MQTT 5?

No. Una conexión 3.1.1 solo recibe los códigos de retorno clásicos de CONNACK y el valor de fallo 0x80 en SUBACK. Conéctate con la versión 5 del protocolo para recibir códigos de motivo detallados.