Selo de estado:
Preview— guia de sintoma → causa → correção para integrações. Atualizado em 2026-09-06.
Encontre o sintoma, confirme a causa e aplique a correção. Se não resolver, abra
um chamado (ver Suporte) com o código HTTP e a mensagem
error exata.
Disponibilidade#
- Cobre as superfícies de desenvolvedor: Autenticação,
API de consulta (fora de GA),
OData/Power BI (
Preview) e Embed (Preview).
Permissões#
- Alguns erros (
403) dependem do papel/escopo da credencial — ver Autenticação.
Autenticação e permissão#
| Sintoma (código · mensagem) | Causa | Correção |
|---|---|---|
401 Chave de API ausente | não enviou a chave | Authorization: Bearer <chave> ou ?api_key=<chave> |
401 Chave inválida ou revogada | chave errada/revogada | gere nova chave (só o dono cria) |
403 em SQL livre (service principal) | papel abaixo de admin | use chave de dados do dono ou eleve o papel |
403 Apenas consultas SELECT | SQL de escrita/DDL | envie só SELECT/WITH … SELECT |
403 fora do workspace / só marts publicados | referência a outro cliente/dataset | consulte só *_gold/*_silver do seu workspace |
Cobrança e limites#
| Sintoma | Causa | Correção |
|---|---|---|
402 | workspace inadimplente/suspenso | regularize o pagamento no app |
429 (+ Retry-After) | estouro de rate limit | respeite o Retry-After; reduza paralelismo/frequência |
503 (+ Retry-After) | limitador de requisições indisponível (fail-closed) | aguarde e repita |
| Custo maior que o esperado | paginação de tabela grande sem filtro | filtre/agregue; no Power BI use refresh incremental em coluna de partição |
Datalake e disponibilidade#
| Sintoma | Causa | Correção |
|---|---|---|
503 Datalake não provisionado | workspace sem datalake em nuvem | confirme o provisionamento do workspace |
503 no feed OData | nuvem própria do cliente caída | tente de novo; verifique a credencial da nuvem |
502 Falha ao executar a consulta | erro no datalake | revise o SQL/tabela; tente novamente |
| Dados "claramente simulados" | ambiente demo (sem o datalake configurado) | esperado em demo; $filter/$orderby/$count respondem 503 |
OData / Power BI / Excel#
| Sintoma | Causa | Correção |
|---|---|---|
501 num filtro | operação fora do subset ($expand, lambdas, aritmética…) | simplifique o $filter ou filtre localmente após um filtro suportado |
400 $skiptoken inválido | link de paginação alterado | siga o @odata.nextLink exatamente como recebido |
400 acima de 1M linhas | profundidade de paginação excedida | use $filter/refresh incremental para reduzir o volume |
| Coluna some no Power BI | é PII ou STRUCT/RECORD | PII não sai pela API; publique colunas planas nos marts |
| Filtro "não dobra" (folding) | operação não suportada como pushdown | reordene: aplique primeiro os filtros que dobram ($filter/$select/$top) |
| Excel/PBI pede login | usou o caminho por header sem Implementation="2.0" | use o M do kit ou o caminho ?api_key= com autenticação Anônima |
Embed SDK#
| Sintoma | Causa | Correção |
|---|---|---|
| Tela de recusa logo ao abrir | token expirado | emita token novo no seu servidor e recrie o embed |
| Recusa persistente | origem fora da allowlist | peça ao suporte para incluir o domínio da sua aplicação |
| Filtros não aplicam | aplicarFiltros antes do onPronto | aplique dentro/depois do onPronto |
filtros_invalidos | estrutura/ids de filtro inválidos | use os ids do editor; leia o onEstado para descobri-los |
| Todo token parou de valer | segredo foi rotacionado | atualize INGESTIA_EMBED_SECRET no seu servidor |
Validação (confirmar a correção)#
- Refaça a chamada e verifique
200+ os cabeçalhos esperados (X-Ingestia-Access-Scope: workspace,OData-Version: 4.0no OData). - Para embed, confirme o disparo de
onPronto.
Custo#
- Diagnosticar não custa; só a extração de linhas gera consumo. Ver Erros e limites.
Segurança#
- Ao relatar um erro, remova segredos do exemplo. Se um segredo apareceu em log/URL compartilhada, revogue/rotacione antes de abrir o chamado.
Limites#
- Este guia cobre os erros previstos das rotas
/api/v1e do embed. Erros não listados: abra chamado com código HTTP + mensagem.
Quando abrir chamado#
- Erro persiste após a correção sugerida, ou é
Crítico/Alto(ver severidades). Inclua horário, workspace, código HTTP e mensagem.
Próximos passos: Erros e limites · Status e limitações · Abrir chamado.
Estado & evidência: sintomas mapeados às respostas reais das rotas /api/v1
e do embed (Preview). Fonte: matriz de estados do produto.