Esta versión (v0.7) todavía no se publicó en npm.
Ir al contenido

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.

ts
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 baseUrl absoluta y tenantHost.
  • Sin fetch en el entorno: pasa fetch en 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 localStorageTokenStore cae a memoria y la sesión muere en el reload. Detéctalo con enginex.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 misma key (por defecto getenginex.tokens).
  • Orígenes diferentes: localStorage es 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.