> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.rhombus.community/llms.txt
> Use this file to discover all available pages before exploring further.

# Solución de problemas de WebSocket

> Diagnostica y resuelve problemas comunes del WebSocket de Rhombus: fallos de conexión, errores de STOMP, heartbeats perdidos, problemas de autenticación y eventos descartados.

<Note>
  Esta página fue traducida automáticamente. Si encuentra errores o tiene sugerencias, [contáctenos](mailto:support@rhombus.com).
</Note>

Esta guía cubre los problemas comunes al trabajar con conexiones WebSocket de Rhombus y cómo resolverlos.

## Problemas de conexión

### No se puede conectar (conexión rechazada)

**Síntomas**: el handshake de WebSocket falla de inmediato con un error de conexión.

**Causas posibles**:

* Un firewall bloquea las conexiones salientes en el puerto 8443
* Hostname incorrecto

**Soluciones**:

1. Verifica el acceso saliente a `ws.rhombussystems.com` en el puerto `8443`:
   ```bash theme={null}
   # Test connectivity
   curl -v https://ws.rhombussystems.com:8443/websocket

   # Test TCP connectivity directly
   nc -zv ws.rhombussystems.com 8443
   ```
2. Comprueba que tu red/firewall permita WSS saliente en el puerto 8443
3. Si estás detrás de un proxy corporativo, asegúrate de que se permitan las solicitudes de actualización (upgrade) de WebSocket

### HTTP 401 Unauthorized

**Síntomas**: el handshake de WebSocket falla con HTTP 401.

**Causas posibles**:

* Token de API inválido
* Token de API expirado
* Falta el header `x-auth-apikey`

**Soluciones**:

1. Verifica que tu token de API funcione con la API REST:
   ```bash theme={null}
   curl -X POST https://api2.rhombussystems.com/api/org/getOrgV2 \
     -H "x-auth-apikey: YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{}'
   ```
2. Regenera el token en la consola de Rhombus en **Settings > API Access**
3. Asegúrate de que el header `x-auth-apikey` esté configurado (no solo el parámetro de query)

### HTTP 403 Forbidden

**Síntomas**: el handshake de WebSocket falla con HTTP 403.

**Causas posibles**:

* El token de API carece de permisos para el acceso a WebSocket
* Se usó un token de partner sin especificar la organización destino
* El token no tiene acceso a la organización especificada

**Soluciones**:

1. Comprueba los permisos del token en la consola de Rhombus
2. Si usas un token de partner, envía el UUID de la organización destino en el **encabezado** `x-auth-org` (el servidor lee `x-auth-org` de los encabezados de la solicitud, no de la cadena de query), mientras que `x-auth-scheme=partner-api-token` permanece en la URL de conexión:

```text theme={null}
   Encabezado: x-auth-org: CLIENT_ORG_UUID
   URL:        wss://ws.rhombussystems.com:8443/websocket?x-auth-scheme=partner-api-token
```

### La autenticación basada en certificados no funciona

**Síntomas**: la conexión falla al usar certificados mTLS.

**Causa**: las conexiones WebSocket **no admiten** autenticación basada en certificados.

**Solución**: genera un token de API para las conexiones WebSocket. La autenticación con certificados solo se admite para la API REST.

## Problemas del protocolo STOMP

### El frame CONNECTED nunca se recibe

**Síntomas**: el WebSocket se conecta correctamente, pero no se recibe ninguna respuesta STOMP `CONNECTED` después de enviar `CONNECT`.

**Causas posibles**:

* Frame STOMP `CONNECT` mal formado
* Falta el terminador nulo (`\x00`)
* Valor de `accept-version` incorrecto

**Soluciones**:

1. Verifica que tu frame incluya el terminador de byte nulo:
   ```python theme={null}
   # Correct
   frame = "CONNECT\naccept-version:1.2\nheart-beat:10000,10000\n\n\x00"

   # Wrong - missing \x00
   frame = "CONNECT\naccept-version:1.2\nheart-beat:10000,10000\n\n"
   ```
2. Asegúrate de que haya una línea vacía (`\n\n`) entre los headers y el cuerpo
3. Usa `accept-version:1.2` (no `1.0` ni `1.1`)

### No se reciben mensajes después de suscribirse

**Síntomas**: la conexión y la suscripción se realizan correctamente, pero no llegan frames MESSAGE.

**Causas posibles**:

* UUID de organización incorrecto en el tópico
* No ocurren eventos en la organización
* Frame de suscripción mal formado

**Soluciones**:

1. Verifica el UUID de tu organización llamando a la API REST:
   ```bash theme={null}
   curl -X POST https://api2.rhombussystems.com/api/org/getOrgV2 \
     -H "x-auth-apikey: YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{}'
   ```
2. Dispara un evento de prueba (por ejemplo, ajusta una configuración de cámara) para confirmar que el flujo está activo
3. Verifica que el formato del tópico sea exactamente `/topic/change/{orgUuid}` sin barras finales ni espacios

## Problemas de estabilidad de la conexión

### La conexión se cae cada \~30 segundos

**Síntomas**: la conexión WebSocket se cierra después de aproximadamente 30 segundos de inactividad.

**Causa**: no se están enviando heartbeats.

**Solución**: implementa el emisor de heartbeats que envía `\n` cada 10 segundos:

```python theme={null}
import threading

def heartbeat_sender(ws, stop_event):
    while not stop_event.is_set():
        ws.send("\n")
        stop_event.wait(10)

stop = threading.Event()
thread = threading.Thread(target=heartbeat_sender, args=(ws, stop), daemon=True)
thread.start()
```

### La conexión se cae de forma intermitente

**Síntomas**: la conexión funciona durante un tiempo y luego se cae de forma impredecible.

**Causas posibles**:

* Inestabilidad de la red
* Mantenimiento del lado del servidor
* Timeout del balanceador de carga

**Soluciones**:

1. Implementa la reconexión automática con backoff:
   ```python theme={null}
   while True:
       try:
           run_websocket_monitor()
       except ConnectionError:
           print("Reconnecting in 5 seconds...")
           time.sleep(5)
   ```
2. Registra los motivos de desconexión para identificar patrones
3. Monitorea la recepción de heartbeats para detectar conexiones muertas de forma proactiva

### Alto uso de memoria con el tiempo

**Síntomas**: la memoria de la aplicación crece de forma constante mientras está conectada.

**Causas posibles**:

* Los eventos se acumulan en una cola sin límite
* No se procesan los mensajes con suficiente rapidez

**Soluciones**:

1. Usa buffers de mensajes con límite:
   ```python theme={null}
   # Use a bounded queue
   from queue import Queue
   event_queue = Queue(maxsize=1000)
   ```
2. Procesa los eventos de forma asíncrona para evitar la contrapresión (backpressure)
3. Descarta o registra los eventos si la cola de procesamiento está llena

## Problemas de procesamiento de eventos

### Eventos faltantes

**Síntomas**: algunos eventos que aparecen en la consola de Rhombus no aparecen en el flujo de WebSocket.

**Causas posibles**:

* El filtrado de eventos es demasiado agresivo
* Una breve desconexión causó la pérdida de eventos
* El evento ocurrió antes de que se estableciera la suscripción

**Soluciones**:

1. Habilita temporalmente todos los eventos para verificar el flujo:
   ```python theme={null}
   # Don't filter by entity type
   if frame["command"] == "MESSAGE":
       print(json.loads(frame["body"]))
   ```
2. Los eventos de WebSocket son solo en tiempo real. Para eventos históricos, usa la API REST
3. Asegúrate de que SUBSCRIBE se envíe antes de esperar eventos

### JSON mal formado en el cuerpo del evento

**Síntomas**: `json.loads()` falla con el cuerpo de MESSAGE.

**Causas posibles**:

* El parser de frames no separa correctamente el cuerpo de los headers
* Bytes nulos o espacios en blanco adicionales en el cuerpo

**Soluciones**:

1. Elimina los bytes nulos antes de parsear:
   ```python theme={null}
   body = frame["body"].strip("\x00").strip()
   payload = json.loads(body)
   ```
2. Verifica que tu parser de frames divida en `\n\n` correctamente (solo la primera ocurrencia)

## Herramientas de depuración

### Habilitar el registro de frames sin procesar

Agrega registro (logging) para ver exactamente qué se envía y se recibe:

```python theme={null}
import logging

logging.basicConfig(level=logging.DEBUG)

# In your message loop:
raw = ws.recv()
logging.debug(f"Received: {repr(raw)}")
```

### Probar con websocat

Usa `wscat` para interactuar manualmente con el endpoint de WebSocket:

```bash theme={null}
# Install
npm install -g wscat

# Connect (note: wscat does not support custom headers natively,
# so use a tool like websocat for full header support)
websocat -H "x-auth-apikey: YOUR_TOKEN" \
  "wss://ws.rhombussystems.com:8443/websocket?x-auth-scheme=api-token"

# Then manually type STOMP frames:
CONNECT
accept-version:1.2
heart-beat:10000,10000

^@
```

<Note>
  `^@` representa el byte nulo (`\x00`). En la mayoría de las terminales, escribe `Ctrl+@` o `Ctrl+Shift+2` para producirlo.
</Note>

### Monitor de la CLI de Rhombus

Usa la [CLI de Rhombus](/es/rhombus-cli) para verificar que tu cuenta y el endpoint de WebSocket funcionen:

```bash theme={null}
# Install the CLI (macOS/Linux)
brew install RhombusSystems/tap/rhombus

# Authenticate
rhombus login

# Test WebSocket monitoring
rhombus monitor --all-events --json
```

Si la CLI funciona pero tu código no, compara los parámetros de conexión que usa tu código con el comportamiento de la CLI. Consulta la [documentación de la CLI de Rhombus](/es/rhombus-cli) para conocer todos los detalles de instalación y uso.

## Cómo obtener ayuda

Si has probado los pasos anteriores y sigues experimentando problemas:

1. Consulta la [documentación de la API de Rhombus](https://api-docs.rhombus.community) para ver actualizaciones
2. Verifica que tu organización de Rhombus tenga habilitado el acceso a WebSocket
3. Contacta al soporte de Rhombus con:
   * El UUID de tu organización
   * El mensaje de error o el código de estado HTTP
   * La marca de tiempo del intento de conexión fallido
   * Tu lenguaje de cliente y la versión de la biblioteca de WebSocket