Troubleshooting
Síntomas comunes en la integración y cómo resolverlos. Todo error del SDK es un EnginexError: empieza mirando error.code, error.status y error.requestId (consulta Errores y Códigos de error).
Operador no identificado (tenant)
Síntoma: las llamadas fallan con un EnginexError con code: 'INVALID_ARGUMENT' y status: 400. El mensaje es unknown domain (cualquier ruta: el gateway no reconoce el dominio enviado en X-Original-Host) u operador não identificado (inicio de sesión, registro y verificación de teléfono). Si el gateway no logra consultar los operadores, el error es UNAVAILABLE (status: 503, mensaje service temporarily unavailable); en ese caso es un problema del gateway, no de tu configuración.
Causa: el gateway descubre el operador por el dominio del sitio (X-Original-Host). Con el proxy de Vite/Next en desarrollo el dominio es localhost:5173, que no está registrado en ningún operador.
Solución: indica el dominio del operador con tenantHost (aplica a llamadas same-origin, es decir, a través del proxy /api). Consulta Desarrollo local y Tenant y dominios.
createEnginexClient({ tenantHost: import.meta.env.VITE_ENGINEX_TENANT })Si llamas al gateway directamente (cross-origin), el SDK no envía X-Original-Host: el operador viene del Host, así que el dominio del gateway debe estar registrado en el operador.
CORS y preflight
Síntoma: NETWORK_ERROR en el browser, con status: 0; en la consola, "blocked by CORS policy" o un OPTIONS (preflight) que falla.
Causa: una llamada cross-origin (baseUrl apuntando al gateway) sin el origen del sitio permitido en el CORS del gateway, o con un header que este no permite.
Solución: prefiere el proxy same-origin: sin baseUrl, el request sale hacia el propio origen y no hay CORS. Si necesitas llamar directamente, pide que se permita el origen del sitio en el gateway.
Respuesta HTML en lugar de JSON (proxy ausente)
Síntoma: VALIDATION_ERROR con el mensaje "Non-JSON response at ... Check the baseUrl and the /api proxy to the gateway."
Causa: /api/v1/... fue respondido por tu propio servidor (normalmente el index.html de la SPA o una página 404) porque el proxy hacia el gateway no existe o no cubre la ruta.
Solución: configura el proxy de /api (Vite, Next.js, Nginx en Instalación) y prueba curl -i http://localhost:5173/api/v1/config: la respuesta debe ser JSON del gateway. Verifica también que el baseUrl termine sin /api (el SDK agrega /api/v1).
CONFIGURATION_ERROR
Síntoma: el primer request rechaza con code: 'CONFIGURATION_ERROR', sin llamar a la red.
Causas y soluciones:
- Fuera del browser (SSR, scripts, pruebas en Node): indica una
baseUrlabsoluta ytenantHost. - Sin
fetchen el entorno: pasafetchen las opciones del cliente. - Cliente descartado: después de
client.dispose()todo método rechaza con este código; crea otro cliente.
El cliente no lanza al crearse, así que el error aparece solo en el primer request, con el mensaje indicando qué falta. Consulta Tenant y dominios.
Sesión que se cae (localStorage y pestañas)
Síntoma: el jugador cierra sesión al recargar, al abrir otra pestaña o en navegación privada.
Verifica:
- Storage no disponible: en Safari privado, con la cuota llena o con cookies/storage bloqueados, el
localStorageTokenStorecae a memoria y la sesión muere en el reload. Detéctalo conenginex.session.get()tras recargar y ofrece iniciar sesión de nuevo. - Más de un cliente/
tokenStore: dos instancias con claves diferentes no comparten sesión. Usa un cliente por app y la mismakey(por defectogetenginex.tokens). - Orígenes diferentes:
localStoragees por origen;www.y el dominio raíz, o puertos distintos, tienen sesiones separadas. - Refresh rechazado: si el gateway rechaza el refresh, la sesión se limpia y se llama a
onSessionExpired. En ese caso es un cierre de sesión esperado (refresh token expirado o revocado).
Entre pestañas del mismo origen la sesión se sincroniza con el evento storage. Consulta Sesión y tokens.
Reloj del dispositivo
Síntoma: refresh en cada request o varios 401 seguidos, sobre todo en dispositivos con fecha y hora incorrectas.
Causa: el SDK decide renovar el access token comparando el exp del JWT con el reloj local. Un reloj adelantado hace que el token parezca siempre a punto de expirar; uno atrasado hace que el SDK use un token ya vencido, y la renovación solo ocurre después del 401.
Solución: pide al jugador que active la fecha y hora automáticas. El SDK se recupera solo (refresh reactivo tras el 401), así que el efecto es solo un request extra.