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.
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
baseUrlabsoluto etenantHost. - Sem
fetchno ambiente: passefetchnas 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
localStorageTokenStorecai para memória e a sessão morre no reload. Detecte comenginex.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 mesmakey(padrãogetenginex.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.