Saltar al contenido

Traducción automática — la versión en portugués es la referencia. Ver en portugués

Troubleshooting (API, OData, Power BI y Embed)

En esta página (12)

Encuentra el síntoma, confirma la causa y aplica la corrección. Si no se resuelve, abre un ticket (consulta Soporte) con el código HTTP y el mensaje error exacto.

Disponibilidad#

Permisos#

  • Algunos errores (403) dependen del rol/alcance de la credencial — consulta Autenticación.

Autenticación y permisos#

Síntoma (código · mensaje)CausaCorrección
401 Chave de API ausente (falta la clave de API)no enviaste la claveAuthorization: Bearer <chave> o ?api_key=<chave>
401 Chave inválida ou revogada (clave inválida o revocada)clave incorrecta/revocadagenera una nueva clave (solo el dueño la crea)
403 en SQL libre (service principal)rol inferior a adminusa la clave de datos del dueño o eleva el rol
403 Apenas consultas SELECT (solo consultas SELECT)SQL de escritura/DDLenvía solo SELECT/WITH … SELECT
403 fora do workspace / só marts publicados (fuera del workspace / solo marts publicados)referencia a otro cliente/datasetconsulta solo *_gold/*_silver de tu workspace

Cobro y límites#

SíntomaCausaCorrección
402workspace moroso/suspendidoregulariza el pago en la app
429 (+ Retry-After)se superó el rate limitrespeta el Retry-After; reduce el paralelismo/frecuencia
503 (+ Retry-After)limitador de solicitudes no disponible (fail-closed)espera y repite
Costo mayor de lo esperadopaginación de tabla grande sin filtrofiltra/agrega; en Power BI usa refresh incremental en una columna de partición

Datalake y disponibilidad#

SíntomaCausaCorrección
503 Datalake não provisionado (datalake no aprovisionado)workspace sin datalake en la nubeconfirma el aprovisionamiento del workspace
503 en el feed ODatala nube propia del cliente está caídainténtalo de nuevo; verifica la credencial de la nube
502 Falha ao executar a consulta (falla al ejecutar la consulta)error en el datalakerevisa el SQL/tabla; inténtalo de nuevo
Datos "claramente simulados"entorno demo (sin el datalake configurado)esperado en demo; $filter/$orderby/$count responden 503

OData / Power BI / Excel#

SíntomaCausaCorrección
501 en un filtrooperación fuera del subconjunto ($expand, lambdas, aritmética…)simplifica el $filter o filtra localmente después de un filtro compatible
400 $skiptoken inválidoenlace de paginación alteradosigue el @odata.nextLink exactamente como lo recibiste
400 por encima de 1M filasprofundidad de paginación excedidausa $filter/refresh incremental para reducir el volumen
Una columna desaparece en Power BIes PII o STRUCT/RECORDla PII no sale por la API; publica columnas planas en los marts
El filtro "no hace folding"operación no compatible como pushdownreordena: aplica primero los filtros que hacen folding ($filter/$select/$top)
Excel/PBI pide inicio de sesiónusaste el camino por header sin Implementation="2.0"usa el M del kit o el camino ?api_key= con autenticación Anónima

Embed SDK#

SíntomaCausaCorrección
Pantalla de rechazo apenas se abretoken expiradoemite un token nuevo en tu servidor y recrea el embed
Rechazo persistenteorigen fuera de la allowlistpide a soporte que incluya el dominio de tu aplicación
Los filtros no se aplicanaplicarFiltros antes del onProntoaplícalos dentro/después del onPronto
filtros_invalidosestructura/ids de filtro inválidosusa los ids del editor; lee el onEstado para descubrirlos
Todos los tokens dejaron de funcionarse rotó el secretoactualiza INGESTIA_EMBED_SECRET en tu servidor

Validación (confirmar la corrección)#

  • Repite la llamada y verifica 200 + los encabezados esperados (X-Ingestia-Access-Scope: workspace, OData-Version: 4.0 en OData).
  • Para embed, confirma que se dispare onPronto.

Costo#

  • Investigar no cuesta; solo la extracción de filas genera consumo. Consulta Errores y límites.

Seguridad#

  • Al reportar un error, quita los secretos del ejemplo. Si un secreto apareció en un log/URL compartida, revócalo/rótalo antes de abrir el ticket.

Límites#

  • Esta guía cubre los errores previstos de las rutas /api/v1 y del embed. Errores no listados: abre un ticket con código HTTP + mensaje.

Cuándo abrir un ticket#

  • El error persiste después de la corrección sugerida, o es Crítico/Alto (consulta severidades). Incluye hora, workspace, código HTTP y mensaje.

Próximos pasos: Errores y límites · Estado y limitaciones · Abrir un ticket.

Enlaces relacionados