Códigos de Retorno do CONNACK MQTT de 0 a 5 Explicados (MQTT 3.1.1)

Os códigos de retorno CONNACK MQTT são os seis valores, de 0 a 5, que um broker MQTT 3.1.1 devolve para informar a um client se sua conexão foi aceita e, se não foi, por quê. Este guia explica cada código, mostra como ele aparece em ferramentas e bibliotecas comuns e traz uma correção que você pode aplicar em minutos, com exemplos contra o servidor MQTT público e contra um broker privado.

O que o pacote CONNACK contém

Depois que um client abre uma conexão TCP, seu primeiro pacote deve ser o CONNECT. O broker responde com o CONNACK, um pacote fixo de quatro bytes no MQTT 3.1.1:

20 02 00 05
|  |  |  |
|  |  |  +-- Connect return code (here 5 = Not authorized)
|  |  +----- Connect acknowledge flags (bit 0 = Session Present)
|  +-------- Remaining length (always 2)
+----------- Packet type 2 (CONNACK), flags 0

A flag Session Present informa ao client se o broker retomou uma sessão armazenada, o que importa para sessões persistentes. O código de retorno é o assunto deste artigo. Se ele for qualquer coisa diferente de 0, o broker fecha a conexão de rede logo depois de enviar o CONNACK, e o client precisa corrigir a causa antes de tentar de novo. Para o layout completo de bytes deste e de outros pacotes, veja o guia sobre a estrutura de pacotes MQTT.

Códigos de retorno CONNACK MQTT em resumo

Os valores de 6 a 255 são reservados no MQTT 3.1.1. Se sua biblioteca informa um deles, normalmente ela está decodificando por engano um reason code do MQTT 5, o que significa que client e broker discordam sobre a versão do protocolo.

Como cada código de retorno aparece nas suas ferramentas

As mensagens de erro variam de ferramenta para ferramenta, o que torna a busca confusa. Veja como os mesmos códigos aparecem em três clients comuns:

O Paho mapeia internamente os códigos do 3.1.1 para os nomes dos reason codes do MQTT 5, então você pode ver a redação do MQTT 5 mesmo em uma conexão 3.1.1. A referência de reason codes do MQTT mostra o mapeamento completo.

Código 1: Unacceptable Protocol Version

O pacote CONNECT carrega um byte de nível de protocolo: 4 para MQTT 3.1.1, 5 para MQTT 5.0 e 3 para o antigo MQTT 3.1. Se o broker não suporta o nível solicitado, responde com o código 1.

Como corrigir:

• Defina a versão do protocolo explicitamente em vez de confiar nos padrões da biblioteca. Nas ferramentas do Mosquitto use -V mqttv311 ou -V mqttv5, no Paho use protocol=mqtt.MQTTv311, no MQTT.js use protocolVersion: 4 ou 5.
• Evite o MQTT 3.1 (nível 3). Brokers MQTT gerenciados modernos, como o ConnectMQ, suportam 3.1.1 e 5.0.
• Se você está atrás de um proxy ou gateway, confirme que ele repassa o MQTT sem alterações.

Código 2: Identifier Rejected

O broker não aceitou o identificador do client. Motivos comuns:

• Client ID vazio com clean session desativado. O MQTT 3.1.1 só permite um client ID de comprimento zero junto com clean session, e muitos brokers rejeitam IDs vazios de qualquer forma. Sempre defina um ID não vazio.
• Caracteres ou comprimento fora das regras do broker. Use letras, dígitos e hifens, e mantenha os IDs razoavelmente curtos.
• Client ID vinculado às credenciais. Alguns brokers vinculam um client ID a uma conta específica. Em um broker privado do ConnectMQ, os client IDs são vinculados às credenciais emitidas no portal, então use o client ID mostrado lá junto com o respectivo username.

No servidor MQTT público, qualquer ID não vazio e único funciona. O guia de client ID MQTT aborda estratégias de nomenclatura para frotas.

Código 3: Server Unavailable

A conexão de rede funcionou, mas o broker não pode atender MQTT no momento. Isso costuma ser transitório: um reinício, sobrecarga ou manutenção. Implemente backoff exponencial com jitter em vez de reconectar imediatamente; milhares de dispositivos reconectando ao mesmo tempo podem manter sobrecarregado um broker que está se recuperando.

Código 4: Bad User Name or Password

O broker verificou as credenciais e elas não conferem. Na prática:

• Copie de novo o username e o password da fonte oficial; espaços no final e campos trocados são comuns.
• Verifique se sua biblioteca realmente envia o password. Algumas APIs exigem username_pw_set() antes de connect().
• Cuidado com caracteres especiais em passwords sendo alterados pelas aspas do shell. Coloque-os entre aspas simples na linha de comando.
• Não faça loop em caso de falha. Os brokers costumam se proteger contra tentativas de força bruta, e o ConnectMQ bloqueia um endereço IP após repetidas falhas de login.

Código 5: Not Authorized

O broker entendeu quem você é, mas recusa a conexão. As causas incluem usar credenciais de outro broker, um client ID que não confere, uma conta desativada ou uma cota esgotada. Esta é a recusa mais comum em brokers privados e tem seu próprio checklist passo a passo em como corrigir MQTT connection refused: not authorized.

Reproduzindo códigos CONNACK com segurança

Ver os códigos com os próprios olhos facilita reconhecê-los nos logs de produção. Primeiro, uma conexão bem-sucedida ao servidor MQTT público (gratuito), que serve para testes e não para dados de produção, com saída de debug ativada:

mosquitto_sub -h broker.connectmq.com -p 1883 -i connack-test-4e8b \
  -t "connectmq/demo/4e8b/#" -V mqttv311 -d

A flag -d imprime Client connack-test-4e8b received CONNACK (0), com o código de retorno entre parênteses. Contra um broker privado, um password propositalmente errado mostra a recusa:

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u YOUR_USERNAME -P wrong-password -i YOUR_CLIENT_ID \
  -t "test/#" -V mqttv311 -d

Rode isso apenas uma ou duas vezes; falhas repetidas podem provocar o bloqueio do IP.

Tratando códigos de retorno em Python

Este client com paho-mqtt 2.x se conecta com MQTT 3.1.1, registra o código e para, em vez de tentar de novo, em erros que precisam de atenção humana:

import paho.mqtt.client as mqtt

# O Paho mapeia os códigos 1, 2, 4, 5 do 3.1.1 para os valores 0x84, 0x85, 0x86, 0x87 do MQTT 5
FATAL = {0x84, 0x85, 0x86, 0x87}

def on_connect(client, userdata, flags, reason_code, properties):
    if not reason_code.is_failure:
        print("Connected, session present:", flags.session_present)
        client.subscribe("connectmq/demo/4e8b/#")
        return
    print(f"Connection refused: {reason_code}")
    if reason_code.value in FATAL:
        print("Configuration problem, not retrying")
        client.disconnect()
        client.loop_stop()

client = mqtt.Client(
    mqtt.CallbackAPIVersion.VERSION2,
    client_id="connack-py-4e8b",
    protocol=mqtt.MQTTv311,
)
client.on_connect = on_connect
client.connect("broker.connectmq.com", 1883, keepalive=60)
client.loop_forever()

Tratando códigos de retorno em Node.js

O MQTT.js emite um evento error com uma propriedade code contendo o valor numérico do CONNACK:

const mqtt = require("mqtt");

const client = mqtt.connect("mqtts://broker.connectmq.com:8883", {
  clientId: "YOUR_CLIENT_ID",
  username: "YOUR_USERNAME",
  password: "YOUR_PASSWORD",
  protocolVersion: 4,
  reconnectPeriod: 5000,
});

client.on("connect", () => console.log("CONNACK 0: connected"));

client.on("error", (err) => {
  console.error(`CONNACK ${err.code}: ${err.message}`);
  if ([1, 2, 4, 5].includes(err.code)) {
    client.end(true); // para de reconectar em erros de configuração
  }
});

Checklist rápido de solução de problemas do CONNACK

1. Você consegue sequer alcançar o host e a porta? Um timeout significa que nenhum CONNACK foi enviado; verifique DNS, firewall e porta.
2. Você está usando TLS na 8883 e TCP simples na 1883, e não o contrário?
3. A versão do protocolo está explícita e é suportada?
4. O client ID não está vazio, é único e é o que foi emitido com suas credenciais?
5. O username e o password estão exatamente como foram emitidos?
6. Sua lógica de reconexão para nos códigos 1, 2, 4 e 5 em vez de martelar o broker?

Tenha feedback claro de conexão com o ConnectMQ

O ConnectMQ é um broker MQTT gerenciado que suporta MQTT 3.1.1 e 5.0 em TCP 1883, TLS 8883 e WebSockets. O portal gera username, password e client ID correspondentes para cada broker, o que elimina a causa mais comum dos códigos 2, 4 e 5. Crie um broker Serverless gratuito em app.connectmq.com, sem cartão de crédito. É novo em brokers? Comece por o que um broker MQTT faz ou pelo tutorial de MQTT completo.

Perguntas frequentes

O que significa o código de retorno 0 do CONNACK?

Conexão aceita. O broker aceitou o CONNECT, e a flag Session Present no mesmo pacote informa se uma sessão anterior foi retomada.

Qual é a diferença entre os códigos de retorno 4 e 5?

O código 4 significa que o username ou o password não conferem. O código 5 significa que o broker recusa o client por outro motivo de autorização, como um client ID não vinculado àquelas credenciais ou uma conta que não tem permissão para se conectar.

Por que meu client não recebe nenhum CONNACK?

Se nenhum CONNACK chega, o problema está abaixo do MQTT: host ou porta errados, um firewall ou uma incompatibilidade de TLS, como MQTT simples enviado para a porta 8883. Corrija a conectividade antes de olhar os códigos de retorno.

O MQTT 5 usa os mesmos códigos CONNACK?

Não. O MQTT 5 os substitui por reason codes como 0x86 e 0x87, que trazem mais detalhes. Os seis códigos do 3.1.1 correspondem diretamente a equivalentes no MQTT 5.