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#
- Covers the developer surfaces: Authentication, Query API (early access), OData/Power BI and Embed.
Permissions#
- Some errors (
403) depend on the credential's role/scope — see Authentication.
Authentication and permissions#
| Symptom (code · message) | Cause | Fix |
|---|---|---|
401 Chave de API ausente (API key missing) | the key wasn't sent | Authorization: Bearer <chave> or ?api_key=<chave> |
401 Chave inválida ou revogada (invalid or revoked key) | wrong/revoked key | generate a new key (only the owner creates them) |
403 on free-form SQL (service principal) | role below admin | use the owner's data key or raise the role |
403 Apenas consultas SELECT (SELECT queries only) | write/DDL SQL | send only SELECT/WITH … SELECT |
403 fora do workspace / só marts publicados (outside the workspace / published marts only) | reference to another customer/dataset | query only *_gold/*_silver in your workspace |
Billing and limits#
| Symptom | Cause | Fix |
|---|---|---|
402 | workspace overdue/suspended | settle the payment in the app |
429 (+ Retry-After) | rate limit exceeded | honor Retry-After; reduce parallelism/frequency |
503 (+ Retry-After) | request limiter unavailable (fail-closed) | wait and retry |
| Cost higher than expected | paging a large table without a filter | filter/aggregate; in Power BI use incremental refresh on a partition column |
Datalake and availability#
| Symptom | Cause | Fix |
|---|---|---|
503 Datalake não provisionado (datalake not provisioned) | workspace without a cloud datalake | confirm the workspace's provisioning |
503 on the OData feed | customer's own cloud is down | try again; check the cloud credential |
502 Falha ao executar a consulta (query execution failed) | error in the datalake | review the SQL/table; try again |
| "Clearly simulated" data | demo environment (no datalake configured) | expected in demo; $filter/$orderby/$count return 503 |
OData / Power BI / Excel#
| Symptom | Cause | Fix |
|---|---|---|
501 on a filter | operation 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 altered | follow @odata.nextLink exactly as received |
400 above 1M rows | paging depth exceeded | use $filter/incremental refresh to reduce the volume |
| Column disappears in Power BI | it's PII or STRUCT/RECORD | PII doesn't leave through the API; publish flat columns in the marts |
| Filter "doesn't fold" | operation not supported as pushdown | reorder: apply the folding filters first ($filter/$select/$top) |
| Excel/PBI asks for login | used the header path without Implementation="2.0" | use the M from the kit or the ?api_key= path with Anonymous authentication |
Embed SDK#
| Symptom | Cause | Fix |
|---|---|---|
| Refusal screen right on open | expired token | issue a new token on your server and recreate the embed |
| Persistent refusal | origin outside the allowlist | ask support to add your application's domain |
| Filters don't apply | aplicarFiltros before onPronto | apply inside/after onPronto |
filtros_invalidos | invalid filter structure/ids | use the ids from the editor; read onEstado to discover them |
| Every token stopped working | the secret was rotated | update 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.0on OData). - For embed, confirm that
onProntofires.
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/v1routes 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.