Esta versão (v0.7) ainda não foi publicada no npm.
Pular para o conteúdo

Troubleshooting ​

Sintomas comuns na integração e como resolvê-los. Todo erro do SDK é um EnginexError: comece olhando error.code, error.status e error.requestId (veja Erros e Códigos de erro).

Operador não identificado (tenant) ​

Sintoma: as chamadas falham com EnginexError de code: 'INVALID_ARGUMENT' e status: 400. A mensagem é unknown domain (qualquer rota: o gateway não reconhece o domínio enviado em X-Original-Host) ou operador não identificado (login, cadastro e verificação de telefone). Se o gateway não conseguir consultar os operadores, o erro é UNAVAILABLE (status: 503, mensagem service temporarily unavailable); nesse caso é problema do gateway, não da sua configuração.

Causa: o gateway descobre o operador pelo domínio do site (X-Original-Host). Com o proxy do Vite/Next em desenvolvimento o domínio é localhost:5173, que não está cadastrado em nenhum operador.

Solução: informe o domínio do operador com tenantHost (vale para chamadas same-origin, isto é, pelo proxy /api). Veja Desenvolvimento local e Tenant e domínios.

ts
createEnginexClient({ tenantHost: import.meta.env.VITE_ENGINEX_TENANT })

Se você chama o gateway direto (cross-origin), o SDK não envia X-Original-Host: o operador vem do Host, então o domínio do gateway precisa estar cadastrado no operador.

CORS e preflight ​

Sintoma: NETWORK_ERROR no browser, com status: 0; no console, "blocked by CORS policy" ou um OPTIONS (preflight) que falha.

Causa: chamada cross-origin (baseUrl apontando para o gateway) sem a origem do site liberada no CORS do gateway, ou com um header que ele não permite.

Solução: prefira o proxy same-origin: sem baseUrl, o request sai para a própria origem e não há CORS. Se precisa chamar direto, peça a liberação da origem do site no gateway.

Resposta HTML em vez de JSON (proxy ausente) ​

Sintoma: VALIDATION_ERROR com a mensagem "Non-JSON response at ... Check the baseUrl and the /api proxy to the gateway."

Causa: /api/v1/... foi respondido pelo seu próprio servidor (normalmente o index.html da SPA ou uma página 404) porque o proxy para o gateway não existe ou não cobre o caminho.

Solução: configure o proxy de /api (Vite, Next.js, Nginx em Instalação) e teste curl -i http://localhost:5173/api/v1/config: a resposta deve ser JSON do gateway. Confira também se o baseUrl termina sem /api (o SDK acrescenta /api/v1).

CONFIGURATION_ERROR ​

Sintoma: o primeiro request rejeita com code: 'CONFIGURATION_ERROR', sem chamar a rede.

Causas e soluções:

  • Fora do browser (SSR, scripts, testes em Node): informe baseUrl absoluto e tenantHost.
  • Sem fetch no ambiente: passe fetch nas opções do cliente.
  • Cliente descartado: depois de client.dispose() todo método rejeita com este código; crie outro cliente.

O cliente não lança na criação, então o erro aparece só no primeiro request, com a mensagem indicando o que falta. Veja Tenant e domínios.

Sessão caindo (localStorage e abas) ​

Sintoma: o jogador é deslogado ao recarregar, ao abrir outra aba ou em navegação anônima.

Verifique:

  • Storage indisponível: em Safari privado, com cota cheia ou bloqueio de cookies/storage, o localStorageTokenStore cai para memória e a sessão morre no reload. Detecte com enginex.session.get() após recarregar e ofereça login de novo.
  • Mais de um cliente/tokenStore: duas instâncias com chaves diferentes não compartilham sessão. Use um cliente por app e a mesma key (padrão getenginex.tokens).
  • Origens diferentes: localStorage é por origem; www. e o domínio raiz, ou portas distintas, têm sessões separadas.
  • Refresh recusado: se o gateway recusar o refresh, a sessão é limpa e onSessionExpired é chamado. Nesse caso é logout esperado (refresh token expirado ou revogado).

Entre abas da mesma origem a sessão é sincronizada pelo evento storage. Veja Sessão e tokens.

Relógio do dispositivo ​

Sintoma: refresh a cada request ou vários 401s seguidos, sobretudo em dispositivos com data e hora erradas.

Causa: o SDK decide renovar o access token comparando o exp do JWT com o relógio local. Um relógio adiantado faz o token parecer sempre prestes a expirar; um atrasado faz o SDK usar um token já vencido, e a renovação só acontece depois do 401.

Solução: peça ao jogador para ativar a data e hora automáticas. O SDK se recupera sozinho (refresh reativo após o 401), então o efeito é só um request extra.