Problemas com o embed

Tipo

Solução de problemas

Para

Parceiro whitelabel, Desenvolvedor

Os problemas do embed se concentram em cinco pontos: login e iframe, criação do tenant, carga dos dados, usuários e limite de pedidos. Cada tabela vai do sintoma à causa e ao conserto. Os códigos de erro completos estão na referência da API.

Login e iframe

Sintoma	Causa	O que fazer
O iframe mostra a tela de login do DataViz depois de um tempo aberto	O token da URL vale 1 hora a partir de quando foi gerado, e navegar não estica o prazo	Gere uma URL nova a cada abertura e recarregue o iframe antes de completar 1 hora. Veja Quanto tempo a sessão dura
A sessão cai logo na primeira página, só em alguns navegadores	O DataViz está num domínio diferente do seu sistema, e o navegador bloqueia o cookie de terceiros	Ponha o DataViz num subdomínio do seu sistema. Veja Marca e domínio
A url abre dataviz.horusbi.com.br no lugar do seu domínio	O tenant foi criado sem dominio	Grave o dominio do tenant com PUT /v1/tenants. Para os próximos tenants, mande dominio na criação ou configure o domínio principal do Cliente no HEC
A url não abre, e o host aparece com vírgulas	O domínio do tenant tem mais de um endereço	Monte a URL a partir do token: https://<seu-dominio>/auth/api/<token>?showMenu=0
HTTP 401, Unauthorized	Tenant Token ausente, errado ou regenerado no HEC, ou o tenant está inativo	Pegue o token atual na aba Desenvolvedor do tenant, ou em GET /v1/tenants
HTTP 404, USER_NOT_FOUND	O e-mail não está vinculado a este tenant	Crie o usuário antes de gerar o login
HTTP 403, USER_LOGIN_NOT_ALLOWED	O e-mail é de alguém da equipe HorusBI	Use um usuário do tenant
O usuário entra e não vê nenhum Dashboard	O usuário não tem grupo nem Mesa	Dê um grupo ou uma Mesa. Veja Dar acesso aos Dashboards
O ref abre a página errada ou quebra	A rota tem acento ou emoji	Use só caracteres ASCII na rota antes de codificar em Base64
Desde 28/10/2026, erros de login e de usuário caem no catch da integração	Esses erros passaram de HTTP 200 para o status da causa (404, 403, 409), com o mesmo corpo	Trate o status 4xx como resposta da API e leia code no corpo

Criação do tenant

Sintoma	Causa	O que fazer
A criação estoura o tempo do seu cliente HTTP	A chamada só responde depois de aplicar o template inteiro, o que leva dezenas de segundos	Use timeout de pelo menos 2 minutos. O tenant pode ter sido criado mesmo assim: repita com o mesmo external_id
HTTP 400, TENANT_NAME_TAKEN ao tentar de novo depois de uma falha	A primeira tentativa já gravou o tenant	Crie sempre com external_id, que torna a repetição segura. Sem ele, procure o tenant em GET /v1/tenants e aplique o template nele
HTTP 400, TENANT_NAME_TAKEN num nome que você nunca usou	O nome do tenant é único na plataforma inteira, entre todos os Clientes	Inclua no nome o ID do cliente no seu sistema
TEMPLATE_NOT_FOUND com um id que existe (HTTP 400 na criação, 404 no apply)	O template é de outro Cliente	Use um template do seu Cliente, listado em GET /v1/tenants/templates
HTTP 400, AGENT_TOKEN_INVALID	O token do Agente ETL não existe	Copie o token em HorusETL › Agentes, ou crie o tenant sem token para ganhar um agente só dele
HTTP 400, INVALID_VARIABLES	Alguma variável foi com valor null	Mande texto vazio ou tire a variável do pedido
status: "failed" com errorCode: "INTERRUPTED"	A montagem ficou mais de 30 minutos parada, porque o servidor parou no meio	Aplique o template de novo com POST /v1/tenant/templates/apply
status: "awaiting_credentials"	Há conexão do template sem nenhum campo preenchido	Preencha as conexões
O tenant ficou inativo depois de um PUT /v1/tenants	ativo é obrigatório em todo PUT, e foi com false	Mande sempre o valor atual de ativo e confira o efeito na cobrança em Desativar e excluir
Uma variável sumiu depois de um PUT /v1/tenants	A lista de development_variables substitui a anterior inteira	Mande todas as variáveis em cada PUT

Carga dos dados

Sintoma	Causa	O que fazer
Os Dashboards do tenant novo estão vazios	A criação não dispara carga	Dispare os agendamentos do tenant
A execução termina com AGENT_OFFLINE	Nenhum Agente ETL ativo para o tenant. Com agente dedicado, ele ainda não foi instalado na rede do cliente	Instale ou ligue o agente e dispare de novo
A execução termina com NOT_STARTED	O agente não começou a carga em 2 horas	Confira se o agente está ligado e com a fila livre
A primeira carga falha com FLOW_FAILED	Variável ou conexão do template ficou vazia	Veja variaveisVazias e credenciaisVazias na resposta da criação e preencha
Disparar de novo não começa outra carga	Já há uma carga aberta do mesmo agendamento ou Dataflow	A resposta traz o executionId dela, com alreadyRunning: true. Acompanhe esse
Os Dashboards ficaram vazios depois de aplicar uma versão nova do template	O apply recriou tabelas, que ficam vazias até a próxima carga	Recarregue as tabelas reconstruídas
Os Dashboards ficaram vazios depois de reativar o tenant	A limpeza diária do DW apagou os dados das tabelas enquanto o tenant estava desativado	Dispare a carga de novo

Usuários

Sintoma	Causa	O que fazer
HTTP 409, USER_LOGIN_TAKEN	O e-mail já está vinculado a este tenant	Use PUT /v1/tenant/users para mudar as permissões
HTTP 409, USER_QUOTA_EXCEEDED	O tenant chegou à franquia de usuários contratada	Remova um usuário ou aumente a franquia
A password enviada não vale	O e-mail já existia em outro tenant, e quem já existe mantém a senha	Nada a fazer pela API. O usuário entra pelo login transparente ou com a senha que já tinha
O nome do usuário mudou em outro tenant	O usuário é da plataforma, e nome vale para todos os tenants dele	Mande nome só quando quiser mudar em todos
O usuário saiu de um grupo sem ninguém pedir	Cada lista enviada no PUT substitui a anterior	Mande a lista completa de grupos, Mesas e restrições
HTTP 403, ADMIN_GROUP_NOT_ALLOWED	A API não dá o grupo de administrador	Dê esse grupo no HEC
HTTP 403, MANAGED_BY_PROVIDER	Em /v1/tenant/users, o grupo é um grupo padrão do Cliente invisível para o tenant. Em /v1/tenant/groups, o grupo é gerenciado pelo Cliente	Faça a alteração no HEC, no cadastro do Cliente

Limite de pedidos

Sintoma	Causa	O que fazer
HTTP 429, Too Many Requests	Mais de 100 pedidos por segundo do mesmo IP	Espere os segundos do header Retry-After e repita. Veja Limite de pedidos