Esta página ayuda cuando un dispositivo no puede conectarse a Hermetry, se le rechaza el inicio de sesión o sigue perdiendo su conexión. Cubre MQTT y la API HTTP del dispositivo. Para dispositivos LoRaWAN, consulte Solución de problemas de uniones; para dispositivos con sondeo, consulte Intervalos de sondeo, retroceso y cuota.
Dónde mirar primero
| Lugar | Muestra |
|---|---|
| La pestaña Log del dispositivo | Cada rechazo de inicio de sesión con su motivo, y cada desconexión con su motivo. El motivo de un rechazo nunca se envía al dispositivo: solo está aquí. |
| La tarjeta Connection details del dispositivo | El host del broker y los puertos que debe usar su dispositivo |
| El registro propio del cliente | El código CONNACK o el estado HTTP recibido, o el error de TLS |
Paso 1: ¿Puede el dispositivo alcanzar el broker?
| Síntoma en el dispositivo | Causa | Solución |
|---|---|---|
| La resolución DNS falla o la conexión agota el tiempo de espera | Host incorrecto, o un cortafuegos bloquea el puerto de salida | Use el host de la tarjeta Connection details, para la región de su organización. Permita TCP 8883 de salida (y 443 para HTTPS). |
| Falla el handshake TLS | El dispositivo se conecta por dirección IP (se requiere SNI), no tiene paquete de CA o su reloj va muy desfasado, por lo que el certificado parece no válido | Conéctese por nombre de host; use el almacén de CA del sistema; ajuste el reloj (NTP) |
| TLS falla en un dispositivo muy pequeño | Solo admite suites de cifrado antiguas o TLS 1.0/1.1 | TLS 1.2 es el mínimo, con suites ECDHE y GCM o ChaCha20. Actualice la biblioteca TLS. |
| Se rechaza el puerto 1883 | El perfil es solo TLS (puerto 8883), el valor predeterminado | Use 8883 o, solo en una red privada, permita MQTT sin cifrar en el perfil |
| Se rechaza un certificado de cliente durante el handshake | El certificado no procede de la CA de dispositivos de Hermetry, o fue revocado | Un certificado no confiable termina el handshake; no hay alternativa con contraseña. Consulte Certificados de dispositivo. |
Consulte Seguridad del transporte de dispositivos.
Paso 2: ¿Se acepta el inicio de sesión?
MQTT responde al CONNECT con un código CONNACK:
| CONNACK | Significado | Causas habituales |
|---|---|---|
| 1 | Versión de protocolo no admitida | El cliente envía MQTT 5. Hermetry usa MQTT 3.1.1. |
| 2 | ID de cliente rechazado | El ID de cliente está vacío, tiene más de 64 caracteres o contiene caracteres fuera de A–Z a–z 0–9 . _ : - |
| 3 | Servidor no disponible | El servicio se está iniciando o está ocupado, o su dirección está bloqueada brevemente tras varios inicios de sesión fallidos. Espere y reintente con jitter. |
| 4 | Usuario o contraseña incorrectos | El token o la contraseña son incorrectos, se rotaron o se revocaron; un usuario sin contraseña se interpreta como token de acceso |
| 5 | No autorizado | Consulte la tabla siguiente. El motivo exacto está en la pestaña Log del dispositivo. |
| Motivo del CONNACK 5 | Solución |
|---|---|
| El dispositivo está deshabilitado | Habilítelo en la página del dispositivo |
| El certificado está revocado o caducado | Deje que el dispositivo lo renueve, o recupérelo. Consulte Certificados de dispositivo. |
| El perfil no permite este tipo de inicio de sesión | Allowed authentication en la pestaña Transport & auth del perfil |
| La dirección del dispositivo está fuera de las Allowed networks del perfil | Añada la red, o compruebe qué dirección pública usa realmente su sitio (NAT, operador móvil) |
| MQTT sin cifrar en un perfil solo TLS | Use el puerto 8883 |
| La organización está suspendida | Pida ayuda a un propietario de la organización. Consulte Organizaciones e inquilinos. |
| Se ha alcanzado el límite de dispositivos o de dispositivos conectados del plan | Consulte Planes y el complemento IoT |
Por HTTP, las mismas comprobaciones responden 401 (token ausente o desconocido), 403 (deshabilitado, suspendido, fuera de las redes permitidas, o una consulta de comandos por HTTP sin cifrar que el perfil no permite: tls_required) o 404 (un token en la URL en un perfil sin Token in the URL). Consulte API HTTP del dispositivo.
Recordatorios de inicio de sesión
| Credencial | ID de cliente | Usuario | Contraseña |
|---|---|---|---|
| Token de acceso | cualquier ID válido | el token | vacío |
| MQTT básico | cualquiera, o el fijado | el usuario | la contraseña |
| Certificado X.509 | el número de serie del dispositivo, igual al CN del certificado | ignorado | vacío |
El secreto de una credencial se muestra una sola vez, al crearla o rotarla. Si se perdió, rótela y actualice el dispositivo. Consulte Credenciales de dispositivo.
Paso 3: El dispositivo se conecta y luego se desconecta
La pestaña Log indica el motivo de la desconexión:
| Motivo | Significado | Solución |
|---|---|---|
keepalive_timeout | No llegó nada dentro del tiempo de keepalive | Use un keepalive de 30 a 300 segundos y envíe PINGREQ; revise el enlace móvil |
takeover | Una segunda conexión del mismo dispositivo tomó el control | Dos dispositivos comparten una credencial, o un cliente se reconecta sin cerrar el socket anterior. Dé a cada dispositivo su propia credencial. |
auth_revoked | La credencial, el dispositivo o la organización ya no están permitidos | Las sesiones se vuelven a comprobar cada 60 segundos aproximadamente; una credencial rotada termina la sesión anterior |
rate_limit | El dispositivo siguió superando su límite de tasa (más de tres veces su cuota por minuto descartada dentro de un minuto) | Agrupe las lecturas, envíe con menor frecuencia o aumente los límites del perfil |
inflight_exceeded | Demasiados mensajes QoS 1 sin confirmar (20 por defecto) | Espere los PUBACK antes de enviar más |
server_shutdown | Se reinició un nodo del broker | Reconecte; no hay nada que corregir |
uplink_window_expired | Terminó la ventana en línea de Recent message | Esperado en dispositivos que solo se conectan para enviar |
protocol_error, socket_error | El cliente incumplió el protocolo, o falló la red | Actualice el cliente; revise el enlace |
Un dispositivo cuya sesión se toma una y otra vez desde dos redes queda retenido durante un tiempo, y sus administradores reciben un aviso de «takeover fight».
Paso 4: El dispositivo se conecta, pero aparece como desconectado
| Causa | Comprobar |
|---|---|
| La regla de conexión del perfil | Live connection, Recent message o Last seen only determinan qué significa «en línea». Consulte Estado de conexión y actividad. |
| Cuarentena | Un dispositivo autorregistrado que espera en cuarentena se conecta, pero sus datos se confirman y descartan hasta que un administrador lo active. Consulte Quarantine. |
| El dispositivo es hijo de una pasarela | Su estado proviene de los mensajes v1/gw/connect y v1/gw/disconnect de la pasarela. Consulte Dispositivos detrás de una pasarela. |
Un dispositivo mal configurado bloquea a otros
Los inicios de sesión fallidos repetidos desde una dirección bloquean esa dirección durante un breve tiempo, para todos los dispositivos detrás de ella. Varios dispositivos tras un mismo NAT o router móvil quedan entonces rechazados con CONNACK 3 (HTTP 429). Busque el dispositivo con credenciales incorrectas (su pestaña Log muestra los fallos), corríjalo y deje que los demás reintenten con retroceso.
Comportamiento recomendado del dispositivo
- Conéctese por TLS usando el nombre de host, con un keepalive entre 30 y 300 segundos.
- Tras CONNACK 0, suscríbase a los topics de downlink, solicite los atributos compartidos, informe los atributos de cliente y luego envíe las lecturas en búfer.
- Ante un rechazo, aplique retroceso: reintente CONNACK 3 con jitter; espere al menos 5 minutos tras CONNACK 4; deje de reintentar CONNACK 1 y 2 hasta que cambie la configuración.
Consulte MQTT.

