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#
- Cubre las superficies de desarrollador: Autenticación, API de consulta (acceso anticipado), OData/Power BI y Embed.
Permisos#
- Algunos errores (
403) dependen del rol/alcance de la credencial — consulta Autenticación.
Autenticación y permisos#
| Síntoma (código · mensaje) | Causa | Corrección |
|---|---|---|
401 Chave de API ausente (falta la clave de API) | no enviaste la clave | Authorization: Bearer <chave> o ?api_key=<chave> |
401 Chave inválida ou revogada (clave inválida o revocada) | clave incorrecta/revocada | genera una nueva clave (solo el dueño la crea) |
403 en SQL libre (service principal) | rol inferior a admin | usa la clave de datos del dueño o eleva el rol |
403 Apenas consultas SELECT (solo consultas SELECT) | SQL de escritura/DDL | envía solo SELECT/WITH … SELECT |
403 fora do workspace / só marts publicados (fuera del workspace / solo marts publicados) | referencia a otro cliente/dataset | consulta solo *_gold/*_silver de tu workspace |
Cobro y límites#
| Síntoma | Causa | Corrección |
|---|---|---|
402 | workspace moroso/suspendido | regulariza el pago en la app |
429 (+ Retry-After) | se superó el rate limit | respeta el Retry-After; reduce el paralelismo/frecuencia |
503 (+ Retry-After) | limitador de solicitudes no disponible (fail-closed) | espera y repite |
| Costo mayor de lo esperado | paginación de tabla grande sin filtro | filtra/agrega; en Power BI usa refresh incremental en una columna de partición |
Datalake y disponibilidad#
| Síntoma | Causa | Corrección |
|---|---|---|
503 Datalake não provisionado (datalake no aprovisionado) | workspace sin datalake en la nube | confirma el aprovisionamiento del workspace |
503 en el feed OData | la nube propia del cliente está caída | inténtalo de nuevo; verifica la credencial de la nube |
502 Falha ao executar a consulta (falla al ejecutar la consulta) | error en el datalake | revisa 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íntoma | Causa | Corrección |
|---|---|---|
501 en un filtro | operación fuera del subconjunto ($expand, lambdas, aritmética…) | simplifica el $filter o filtra localmente después de un filtro compatible |
400 $skiptoken inválido | enlace de paginación alterado | sigue el @odata.nextLink exactamente como lo recibiste |
400 por encima de 1M filas | profundidad de paginación excedida | usa $filter/refresh incremental para reducir el volumen |
| Una columna desaparece en Power BI | es PII o STRUCT/RECORD | la PII no sale por la API; publica columnas planas en los marts |
| El filtro "no hace folding" | operación no compatible como pushdown | reordena: aplica primero los filtros que hacen folding ($filter/$select/$top) |
| Excel/PBI pide inicio de sesión | usaste 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íntoma | Causa | Corrección |
|---|---|---|
| Pantalla de rechazo apenas se abre | token expirado | emite un token nuevo en tu servidor y recrea el embed |
| Rechazo persistente | origen fuera de la allowlist | pide a soporte que incluya el dominio de tu aplicación |
| Los filtros no se aplican | aplicarFiltros antes del onPronto | aplícalos dentro/después del onPronto |
filtros_invalidos | estructura/ids de filtro inválidos | usa los ids del editor; lee el onEstado para descubrirlos |
| Todos los tokens dejaron de funcionar | se rotó el secreto | actualiza 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.0en 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/v1y 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.