Consulta de códigos de motivo MQTT
Recebeu um 0x87, um 135 ou “Connection refused: not authorized”? Pesquise todos os reason codes do MQTT 5 e return codes do MQTT 3.1.1 para ver o que significam e como corrigir.
- CONNACK
O servidor rejeitou o usuário ou a senha.
Como corrigir: Revise as credenciais (atenção a espaços no final e maiúsculas/minúsculas) e confirme que o usuário existe no arquivo de senhas ou no backend de autenticação do broker.
Dica: credenciais por usuário e ACLs de tópicos são mais fáceis de acertar quando você controla o broker — com o ConnectMQ você gerencia ambos em um painel.
- CONNACKPUBACKPUBRECSUBACKUNSUBACKDISCONNECT
O cliente não tem permissão para fazer isso — conectar, publicar nesse tópico ou assinar esse filtro.
Como corrigir: Verifique a ACL do broker para esse usuário e tópico. No CONNACK, geralmente significa que o acesso anônimo está desativado e nenhuma credencial foi enviada.
Dica: credenciais por usuário e ACLs de tópicos são mais fáceis de acertar quando você controla o broker — com o ConnectMQ você gerencia ambos em um painel.
- CONNACK
O client ID está bem formado, mas o servidor não o aceita (longo demais, caracteres inválidos ou vazio quando isso não é permitido).
Como corrigir: Use um client ID alfanumérico curto (até 23 caracteres é sempre seguro) ou deixe o broker atribuir um, enviando um ID vazio com clean start.
- DISCONNECT
Outra conexão com o mesmo client ID se conectou, então esta foi derrubada.
Como corrigir: Dê a cada dispositivo e a cada aba do navegador um client ID único. Dois clientes com o mesmo ID vão se desconectar mutuamente em loop.
- DISCONNECT
Nenhum pacote foi recebido dentro de 1,5 × o intervalo de keep alive, então a conexão foi encerrada.
Como corrigir: Garanta que o loop do seu cliente esteja rodando (PINGREQ sendo enviado), evite bloquear a thread de rede ou aumente o intervalo de keep alive.
- CONNACKPUBACKPUBRECSUBACKUNSUBACKDISCONNECT
Algo falhou e o servidor não quer (ou não consegue) dizer o quê.
Como corrigir: Verifique os logs do broker — normalmente eles mostram a causa real. Veja também a propriedade Reason String, se ela foi enviada.
- CONNACKPUBACKPUBRECSUBACKDISCONNECT
Uma cota da implementação ou administrativa foi excedida (mensagens, conexões, armazenamento, …).
Como corrigir: Verifique seu plano ou as cotas do broker, reduza o volume de mensagens ou peça ao operador para aumentar o limite.
Dica: credenciais por usuário e ACLs de tópicos são mais fáceis de acertar quando você controla o broker — com o ConnectMQ você gerencia ambos em um painel.
- 5Connection Refused, not authorized · Conexão recusada, não autorizadoMQTT 3.1.1 · return code do CONNACKCONNACK
O cliente não tem autorização para se conectar.
Como corrigir: Envie credenciais se o acesso anônimo estiver desativado e verifique a ACL do broker para esse usuário.
Dica: credenciais por usuário e ACLs de tópicos são mais fáceis de acertar quando você controla o broker — com o ConnectMQ você gerencia ambos em um painel.
Como funcionam os reason codes do MQTT
Um reason code (código de motivo) é um único byte que o broker (ou o cliente) envia de volta para dizer como uma operação terminou. No MQTT 5 eles aparecem em CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP, SUBACK, UNSUBACK, DISCONNECT e AUTH. A regra é simples: valores abaixo de 0x80 indicam sucesso (às vezes com informação extra, como 0x10 No matching subscribers), e 0x80 ou acima indicam falha. O mesmo número tem o mesmo significado em todos os pacotes em que é permitido, então 0x87 é sempre “Not authorized” — seja na conexão, numa publicação ou numa assinatura.
O MQTT 3.1.1 é bem menos falante. Só o CONNACK traz um return code (0–5), e o SUBACK só consegue dizer “QoS 0/1/2 concedido” ou 0x80 Failure. Uma publicação QoS 0 rejeitada é descartada em silêncio, e muitos brokers simplesmente fecham a conexão TCP quando há erro, então o log do broker costuma ser sua única pista. Se você precisa de relatórios de erro precisos, vale a pena migrar para o MQTT 5.
Como ler os códigos que sua biblioteca mostra
Cada biblioteca cliente exibe os códigos de um jeito. O Paho Python mostra valores decimais (rc=135), o MQTT.js normalmente mostra o número decimal junto com uma mensagem, e as ferramentas de linha de comando do Mosquitto imprimem textos como “Connection Refused: not authorised”. A caixa de busca acima aceita todos eles: digite 135, 0x87, 87 ou uma expressão como keep alive. No MQTT 5 o broker também pode incluir a propriedade Reason String com uma explicação legível — registre-a no log, porque muitas vezes ela é mais específica do que o próprio código.
Os erros que você mais vai encontrar
- 0x86 / return code 4 — usuário ou senha incorretos. Verifique erros de digitação, espaços no final e maiúsculas/minúsculas. Veja o guia de autenticação do Mosquitto para configurar arquivos de senha.
- 0x87 / return code 5 — não autorizado. As credenciais podem estar certas, mas a ACL bloqueia o tópico, ou o broker recusa clientes anônimos.
- 0x8E — sessão assumida por outra conexão. Dois clientes estão usando o mesmo client ID. Gere IDs únicos com o gerador de Client ID.
- 0x8D — timeout de keep alive. O cliente parou de enviar pacotes. Leia como funciona o keep alive do MQTT.
- 0x95 — pacote grande demais. Confira o tamanho da sua mensagem com a calculadora de tamanho de pacote.
Muitos problemas de conexão nem chegam a gerar um reason code — falhas de DNS, portas erradas e erros no handshake TLS acontecem antes de o MQTT começar. Para esses casos, veja os erros comuns de conexão MQTT e a referência de portas MQTT, ou reproduza o problema no cliente MQTT online, que mostra o resultado do CONNACK no log.
Todos os reason codes do MQTT 5
Todos os reason codes definidos na seção 2.4 da especificação OASIS MQTT 5.0. Crie um link para um código com #0x87.
| Código | Nome | Pacotes | Significado e solução |
|---|---|---|---|
| 0x00 dec 0 | Success Sucesso | CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP, UNSUBACK, AUTH | A operação foi concluída com sucesso. Solução: Nada a corrigir — este é o resultado normal. |
| 0x00 dec 0 | Normal disconnection Desconexão normal | DISCONNECT | A conexão foi encerrada de propósito e a Will Message não é enviada. Solução: Nada a corrigir. Se você não esperava a desconexão, verifique qual lado a enviou e por quê. |
| 0x00 dec 0 | Granted QoS 0 QoS 0 concedido | SUBACK | A assinatura foi aceita com QoS máximo 0. Solução: Se você pediu QoS 1 ou 2, o broker rebaixou o nível — verifique a configuração de QoS máximo dele. |
| 0x01 dec 1 | Granted QoS 1 QoS 1 concedido | SUBACK | A assinatura foi aceita com QoS máximo 1. Solução: Se você pediu QoS 2, o broker limita o QoS a 1 — projete para entrega at-least-once (handlers idempotentes). |
| 0x02 dec 2 | Granted QoS 2 QoS 2 concedido | SUBACK | A assinatura foi aceita com QoS máximo 2. Solução: Nada a corrigir — você recebeu entrega exactly-once, como pediu. |
| 0x04 dec 4 | Disconnect with Will Message Desconexão com Will Message | DISCONNECT | O cliente quer se desconectar, mas pede ao servidor que publique a Will Message mesmo assim. Solução: Nada a corrigir — é uma escolha deliberada do cliente. |
| 0x10 dec 16 | No matching subscribers Nenhum assinante correspondente | PUBACK, PUBREC | A mensagem foi aceita, mas ninguém está assinando esse tópico no momento. Solução: Não é um erro. Verifique se o assinante está conectado e se o filtro de tópico dele corresponde exatamente ao tópico (diferencia maiúsculas de minúsculas). |
| 0x11 dec 17 | No subscription existed Não existia assinatura | UNSUBACK | O cliente tentou cancelar a assinatura de um filtro de tópico que não estava assinado. Solução: Garanta que o filtro do unsubscribe seja idêntico, byte a byte, ao usado na assinatura. |
| 0x18 dec 24 | Continue authentication Continuar a autenticação | AUTH | A autenticação estendida está em andamento e é necessária mais uma etapa AUTH. Solução: Seu cliente precisa responder com um pacote AUTH contendo a próxima etapa do método de autenticação. |
| 0x19 dec 25 | Re-authenticate Reautenticar | AUTH | O cliente pede para executar novamente a autenticação estendida em uma conexão existente. Solução: Nada a corrigir — usado para renovar credenciais, como tokens que expiram. |
| 0x80 dec 128 | Unspecified error Erro não especificado | CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK, DISCONNECT | Algo falhou e o servidor não quer (ou não consegue) dizer o quê. Solução: Verifique os logs do broker — normalmente eles mostram a causa real. Veja também a propriedade Reason String, se ela foi enviada. |
| 0x81 dec 129 | Malformed Packet Pacote malformado | CONNACK, DISCONNECT | O pacote recebido não segue a especificação MQTT e não pôde ser interpretado. Solução: Atualize sua biblioteca cliente, garanta que a versão do protocolo seja compatível e verifique se você não está falando MQTT com uma porta que não é MQTT (ou TCP puro com uma porta TLS). |
| 0x82 dec 130 | Protocol Error Erro de protocolo | CONNACK, DISCONNECT | O pacote foi interpretado corretamente, mas violou uma regra do protocolo, como um segundo CONNECT ou uma propriedade duplicada. Solução: Geralmente é um bug na biblioteca cliente ou em código de pacotes próprio. Atualize a biblioteca e evite enviar pacotes fora de ordem. |
| 0x83 dec 131 | Implementation specific error Erro específico da implementação | CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK, DISCONNECT | O pacote é válido, mas o servidor o rejeita por um motivo específico do broker. Solução: Leia a Reason String e a documentação/os logs do broker — a causa depende do broker (plugins, limites, políticas). |
| 0x84 dec 132 | Unsupported Protocol Version Versão do protocolo não suportada | CONNACK | O servidor não suporta a versão do protocolo MQTT solicitada pelo cliente. Solução: Mude o cliente para MQTT 3.1.1 (protocol level 4) ou atualize para um broker que suporte MQTT 5. |
| 0x85 dec 133 | Client Identifier not valid Client ID inválido | CONNACK | O client ID está bem formado, mas o servidor não o aceita (longo demais, caracteres inválidos ou vazio quando isso não é permitido). Solução: Use um client ID alfanumérico curto (até 23 caracteres é sempre seguro) ou deixe o broker atribuir um, enviando um ID vazio com clean start. |
| 0x86 dec 134 | Bad User Name or Password Usuário ou senha incorretos | CONNACK | O servidor rejeitou o usuário ou a senha. Solução: Revise as credenciais (atenção a espaços no final e maiúsculas/minúsculas) e confirme que o usuário existe no arquivo de senhas ou no backend de autenticação do broker. |
| 0x87 dec 135 | Not authorized Não autorizado | CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK, DISCONNECT | O cliente não tem permissão para fazer isso — conectar, publicar nesse tópico ou assinar esse filtro. Solução: Verifique a ACL do broker para esse usuário e tópico. No CONNACK, geralmente significa que o acesso anônimo está desativado e nenhuma credencial foi enviada. |
| 0x88 dec 136 | Server unavailable Servidor indisponível | CONNACK | O servidor MQTT não está disponível no momento. Solução: Tente novamente com backoff exponencial. Se persistir, verifique a saúde do broker, o estado do cluster e janelas de manutenção. |
| 0x89 dec 137 | Server busy Servidor ocupado | CONNACK, DISCONNECT | O servidor está sobrecarregado e recusa a operação; tente novamente mais tarde. Solução: Aguarde e tente de novo com backoff e jitter, para que milhares de dispositivos não reconectem no mesmo instante. |
| 0x8A dec 138 | Banned Banido | CONNACK | Este cliente foi banido por uma ação administrativa. Solução: Entre em contato com o operador do broker. Tentativas de login repetidas com falha ou tráfego abusivo são motivos comuns de banimento. |
| 0x8B dec 139 | Server shutting down Servidor sendo desligado | DISCONNECT | O servidor está sendo desligado. Solução: Reconecte com backoff; use uma sessão persistente para que as assinaturas e as mensagens QoS 1/2 enfileiradas sejam preservadas. |
| 0x8C dec 140 | Bad authentication method Método de autenticação inválido | CONNACK, DISCONNECT | O método de autenticação no CONNECT não é suportado ou não corresponde ao que está em uso. Solução: Remova a propriedade Authentication Method ou defina um método suportado pelo broker (ex.: SCRAM-SHA-256). |
| 0x8D dec 141 | Keep Alive timeout Timeout de keep alive | DISCONNECT | Nenhum pacote foi recebido dentro de 1,5 × o intervalo de keep alive, então a conexão foi encerrada. Solução: Garanta que o loop do seu cliente esteja rodando (PINGREQ sendo enviado), evite bloquear a thread de rede ou aumente o intervalo de keep alive. |
| 0x8E dec 142 | Session taken over Sessão assumida por outra conexão | DISCONNECT | Outra conexão com o mesmo client ID se conectou, então esta foi derrubada. Solução: Dê a cada dispositivo e a cada aba do navegador um client ID único. Dois clientes com o mesmo ID vão se desconectar mutuamente em loop. |
| 0x8F dec 143 | Topic Filter invalid Filtro de tópico inválido | SUBACK, UNSUBACK, DISCONNECT | O filtro de tópico está bem formado, mas não é aceito por este servidor. Solução: Verifique a posição dos curingas (+ precisa ocupar um nível inteiro, # precisa ser o último) e eventuais limites do broker para profundidade ou tamanho do tópico. |
| 0x90 dec 144 | Topic Name invalid Nome de tópico inválido | CONNACK, PUBACK, PUBREC, DISCONNECT | O nome do tópico está bem formado, mas não é aceito pelo cliente ou pelo servidor. Solução: Nunca publique em um tópico que contenha + ou #, evite tópicos vazios e verifique os limites de tamanho/profundidade de tópico do broker. |
| 0x91 dec 145 | Packet Identifier in use Identificador de pacote em uso | PUBACK, PUBREC, SUBACK, UNSUBACK | O identificador de pacote já está em uso por outra troca em andamento. Solução: Geralmente é um bug na biblioteca cliente ou uma sessão restaurada de forma inconsistente. Atualize a biblioteca ou inicie uma sessão limpa. |
| 0x92 dec 146 | Packet Identifier not found Identificador de pacote não encontrado | PUBREL, PUBCOMP | O identificador de pacote é desconhecido — o estado do fluxo QoS 2 foi perdido. Solução: Acontece depois que o estado da sessão é perdido (ex.: clean start ou reinício do broker sem persistência). Ative a persistência no broker. |
| 0x93 dec 147 | Receive Maximum exceeded Receive Maximum excedido | DISCONNECT | Foram enviados mais pacotes PUBLISH QoS 1/2 sem confirmação do que o receptor permite. Solução: Respeite o Receive Maximum do CONNACK/CONNECT; limite as mensagens em trânsito (in-flight) nas configurações do seu cliente. |
| 0x94 dec 148 | Topic Alias invalid Topic Alias inválido | DISCONNECT | Um topic alias era 0, maior que o Topic Alias Maximum ou foi usado antes de ser definido. Solução: Respeite o Topic Alias Maximum anunciado pelo outro lado ou desative os topic aliases. |
| 0x95 dec 149 | Packet too large Pacote grande demais | CONNACK, DISCONNECT | O pacote excede o tamanho máximo de pacote permitido pelo receptor. Solução: Reduza o payload (comprima, divida ou envie uma referência) ou aumente o limite de tamanho de mensagem do broker. |
| 0x96 dec 150 | Message rate too high Taxa de mensagens alta demais | DISCONNECT | O cliente está publicando mais rápido do que o servidor permite. Solução: Limite a frequência das publicações, agrupe leituras em menos mensagens ou aumente o rate limit no broker. |
| 0x97 dec 151 | Quota exceeded Cota excedida | CONNACK, PUBACK, PUBREC, SUBACK, DISCONNECT | Uma cota da implementação ou administrativa foi excedida (mensagens, conexões, armazenamento, …). Solução: Verifique seu plano ou as cotas do broker, reduza o volume de mensagens ou peça ao operador para aumentar o limite. |
| 0x98 dec 152 | Administrative action Ação administrativa | DISCONNECT | A conexão foi encerrada por um administrador. Solução: Entre em contato com o operador do broker — alguém derrubou este cliente manualmente ou via API de administração. |
| 0x99 dec 153 | Payload format invalid Formato de payload inválido | CONNACK, PUBACK, PUBREC, DISCONNECT | O payload não corresponde ao Payload Format Indicator (ex.: marcado como UTF-8, mas não é UTF-8 válido). Solução: Só defina Payload Format Indicator = 1 quando o payload for texto UTF-8 válido; envie dados binários sem ele. |
| 0x9A dec 154 | Retain not supported Retain não suportado | CONNACK, DISCONNECT | O servidor não suporta mensagens retidas, mas o cliente enviou uma. Solução: Desative a flag retain nas publicações e na Will Message, ou use um broker que suporte retain. |
| 0x9B dec 155 | QoS not supported QoS não suportado | CONNACK, DISCONNECT | O cliente usou um QoS maior que o Maximum QoS anunciado pelo servidor no CONNACK. Solução: Leia o Maximum QoS do CONNACK e publique (e defina o Will QoS) nesse nível ou abaixo dele. |
| 0x9C dec 156 | Use another server Use outro servidor | CONNACK, DISCONNECT | O cliente deve usar outro servidor temporariamente. Solução: Leia a propriedade Server Reference e conecte-se ao servidor indicado; implemente suporte a redirecionamento no seu cliente se você roda clusters. |
| 0x9D dec 157 | Server moved Servidor mudou de endereço | CONNACK, DISCONNECT | O servidor mudou permanentemente; o cliente deve usar outro servidor. Solução: Atualize o hostname do broker na sua configuração usando a propriedade Server Reference. |
| 0x9E dec 158 | Shared Subscriptions not supported Assinaturas compartilhadas não suportadas | SUBACK, DISCONNECT | O servidor não suporta assinaturas compartilhadas $share/…. Solução: Use assinaturas normais ou um broker com suporte a shared subscriptions para consumidores com balanceamento de carga. |
| 0x9F dec 159 | Connection rate exceeded Taxa de conexão excedida | CONNACK, DISCONNECT | O cliente se conecta com frequência demais; o limite de taxa de conexão foi atingido. Solução: Adicione backoff exponencial com jitter às reconexões e procure um loop de reconexão (geralmente causado por client IDs duplicados). |
| 0xA0 dec 160 | Maximum connect time Tempo máximo de conexão | DISCONNECT | O tempo máximo de conexão permitido para este cliente foi atingido. Solução: Reconecte; considere uma sessão persistente para não perder nada durante a breve reconexão. |
| 0xA1 dec 161 | Subscription Identifiers not supported Subscription Identifiers não suportados | SUBACK, DISCONNECT | O servidor não suporta a propriedade Subscription Identifier. Solução: Remova o Subscription Identifier do SUBSCRIBE e roteie as mensagens pelo tópico. |
| 0xA2 dec 162 | Wildcard Subscriptions not supported Assinaturas com curingas não suportadas | SUBACK, DISCONNECT | O servidor não suporta assinaturas que contenham os curingas + ou #. Solução: Assine nomes de tópicos exatos ou use um broker que suporte assinaturas com curingas. |
Return codes do MQTT 3.1.1
Return codes 0–5 do CONNACK e o código de falha do SUBACK da especificação MQTT 3.1.1.
| Código | Nome | Pacotes | Significado e solução |
|---|---|---|---|
| 0 dec 0 | Connection Accepted Conexão aceita | CONNACK | O broker aceitou a conexão. Solução: Nada a corrigir. |
| 1 dec 1 | Connection Refused, unacceptable protocol version Conexão recusada, versão de protocolo inaceitável | CONNACK | O broker não suporta o protocol level solicitado pelo cliente. Solução: Configure o cliente para MQTT 3.1.1 (level 4) ou 3.1 (level 3), de acordo com o broker. |
| 2 dec 2 | Connection Refused, identifier rejected Conexão recusada, identificador rejeitado | CONNACK | O client ID é UTF-8 válido, mas não é permitido pelo broker. Solução: Use de 1 a 23 caracteres de [0-9a-zA-Z] ou envie um ID vazio com clean session = true. |
| 3 dec 3 | Connection Refused, server unavailable Conexão recusada, servidor indisponível | CONNACK | A conexão de rede funcionou, mas o serviço MQTT está indisponível. Solução: Tente novamente com backoff e verifique a saúde do broker. |
| 4 dec 4 | Connection Refused, bad user name or password Conexão recusada, usuário ou senha incorretos | CONNACK | O usuário ou a senha estão malformados ou incorretos. Solução: Verifique as credenciais e se o usuário existe no backend de autenticação do broker. |
| 5 dec 5 | Connection Refused, not authorized Conexão recusada, não autorizado | CONNACK | O cliente não tem autorização para se conectar. Solução: Envie credenciais se o acesso anônimo estiver desativado e verifique a ACL do broker para esse usuário. |
| 0x80 dec 128 | Failure Falha | SUBACK | A assinatura foi rejeitada — geralmente por causa de uma ACL ou de um filtro de tópico inválido. Solução: Verifique a sintaxe do filtro e se o usuário tem permissão para assiná-lo. O MQTT 3.1.1 não dá mais detalhes; confira o log do broker. |
Perguntas frequentes sobre reason codes
O que significa o reason code MQTT 0x87 (135)?
0x87 significa Not authorized (não autorizado). No CONNACK, o broker recusou a conexão (muitas vezes porque o acesso anônimo está desativado e nenhuma credencial foi enviada). Em PUBACK, SUBACK ou DISCONNECT, significa que o usuário não tem permissão para aquele tópico na ACL do broker.
Qual a diferença entre reason code e return code?
O MQTT 3.1.1 só tem return codes no CONNACK (0–5) e no SUBACK (0x00–0x02 e 0x80). O MQTT 5 os substituiu por reason codes que aparecem em quase todas as confirmações, no DISCONNECT e no AUTH, e valores 0x80 ou maiores sempre indicam falha.
Por que meu cliente fica desconectando com 0x8E Session taken over?
Duas conexões estão usando o mesmo client ID. Quando a segunda conecta, o broker desconecta a primeira. Se as duas reconectam automaticamente, uma derruba a outra em loop. Dê a cada dispositivo e a cada aba do navegador um client ID único.
Por que recebo o return code 5 no MQTT 3.1.1?
O return code 5 significa Connection Refused, not authorized (conexão recusada, não autorizado). O broker exige autenticação ou o usuário está bloqueado pelas regras de acesso. Envie um usuário e senha válidos e verifique a ACL do broker ou a configuração allow_anonymous.