Skip to content

Automatic translation — the Portuguese version is the reference. View in Portuguese

Troubleshooting (API, OData, Power BI and Embed)

On this page (12)

Find the symptom, confirm the cause and apply the fix. If that doesn't solve it, open a ticket (see Support) with the HTTP code and the exact error message.

Availability#

Permissions#

  • Some errors (403) depend on the credential's role/scope — see Authentication.

Authentication and permissions#

Symptom (code · message)CauseFix
401 Chave de API ausente (API key missing)the key wasn't sentAuthorization: Bearer <chave> or ?api_key=<chave>
401 Chave inválida ou revogada (invalid or revoked key)wrong/revoked keygenerate a new key (only the owner creates them)
403 on free-form SQL (service principal)role below adminuse the owner's data key or raise the role
403 Apenas consultas SELECT (SELECT queries only)write/DDL SQLsend only SELECT/WITH … SELECT
403 fora do workspace / só marts publicados (outside the workspace / published marts only)reference to another customer/datasetquery only *_gold/*_silver in your workspace

Billing and limits#

SymptomCauseFix
402workspace overdue/suspendedsettle the payment in the app
429 (+ Retry-After)rate limit exceededhonor Retry-After; reduce parallelism/frequency
503 (+ Retry-After)request limiter unavailable (fail-closed)wait and retry
Cost higher than expectedpaging a large table without a filterfilter/aggregate; in Power BI use incremental refresh on a partition column

Datalake and availability#

SymptomCauseFix
503 Datalake não provisionado (datalake not provisioned)workspace without a cloud datalakeconfirm the workspace's provisioning
503 on the OData feedcustomer's own cloud is downtry again; check the cloud credential
502 Falha ao executar a consulta (query execution failed)error in the datalakereview the SQL/table; try again
"Clearly simulated" datademo environment (no datalake configured)expected in demo; $filter/$orderby/$count return 503

OData / Power BI / Excel#

SymptomCauseFix
501 on a filteroperation outside the subset ($expand, lambdas, arithmetic…)simplify the $filter or filter locally after a supported filter
400 $skiptoken inválido (invalid $skiptoken)paging link was alteredfollow @odata.nextLink exactly as received
400 above 1M rowspaging depth exceededuse $filter/incremental refresh to reduce the volume
Column disappears in Power BIit's PII or STRUCT/RECORDPII doesn't leave through the API; publish flat columns in the marts
Filter "doesn't fold"operation not supported as pushdownreorder: apply the folding filters first ($filter/$select/$top)
Excel/PBI asks for loginused the header path without Implementation="2.0"use the M from the kit or the ?api_key= path with Anonymous authentication

Embed SDK#

SymptomCauseFix
Refusal screen right on openexpired tokenissue a new token on your server and recreate the embed
Persistent refusalorigin outside the allowlistask support to add your application's domain
Filters don't applyaplicarFiltros before onProntoapply inside/after onPronto
filtros_invalidosinvalid filter structure/idsuse the ids from the editor; read onEstado to discover them
Every token stopped workingthe secret was rotatedupdate INGESTIA_EMBED_SECRET on your server

Validation (confirming the fix)#

  • Repeat the call and check for 200 + the expected headers (X-Ingestia-Access-Scope: workspace, OData-Version: 4.0 on OData).
  • For embed, confirm that onPronto fires.

Cost#

  • Investigating costs nothing; only extracting rows generates usage. See Errors and limits.

Security#

  • When reporting an error, remove secrets from the example. If a secret appeared in a log/shared URL, revoke/rotate it before opening the ticket.

Limits#

  • This guide covers the expected errors of the /api/v1 routes and the embed. Errors not listed: open a ticket with HTTP code + message.

When to open a ticket#

  • The error persists after the suggested fix, or it is Critical/High (see severities). Include time, workspace, HTTP code and message.

Next steps: Errors and limits · Status and limitations · Open a ticket.

Related links