Reference page for everything common to integrations: error format, HTTP codes, limits, rate limit, pagination, idempotency, and the status of webhooks.
Availability#
- Applies to all
/api/v1/**routes. The surfaces are in different states: OData and Embed = available; REST query API = early access.
Permissions#
- See Authentication. Permission errors return
401(credential) or403(insufficient role/scope).
Error format#
Every failure returns JSON with a message in Portuguese and the corresponding HTTP code:
{ "error": "Mensagem explicando o que aconteceu." }OData adds the OData-Version: 4.0 header. Success and error responses
carry X-Ingestia-Access-Scope: workspace and the CORS headers.
HTTP code catalog#
| Code | Meaning | Typical causes |
|---|---|---|
200 | OK | successful read |
204 | No Content | response to the OPTIONS preflight (CORS) |
400 | Bad Request | malformed JSON, missing sql, invalid $skiptoken, pagination beyond the ceiling |
401 | Unauthenticated | missing, invalid, or revoked key |
402 | Payment Required | workspace overdue/suspended — paid extraction blocked |
403 | Forbidden | insufficient role/scope, non-SELECT SQL, reference outside the workspace/marts |
404 | Not Found | nonexistent OData EntitySet (also protects against enumeration) |
429 | Too Many Requests | rate limit exceeded (includes Retry-After) |
501 | Not Implemented | OData operation outside the supported subset (filter/option) |
502 | Datalake error | failed to run the query |
503 | Unavailable | datalake not provisioned, own cloud down, or request limiter unavailable (includes Retry-After) |
About the limiter
503: the/api/v1routes run paid processing in the datalake. If the rate limit service becomes unavailable, the API denies (503) instead of allowing traffic with no ceiling (fail-closed behavior). RespectRetry-After.
Rate limit#
Limits per 1-minute window, applied per key and per workspace (a leaked key can't exceed the workspace ceiling):
| Bucket | Per key | Per workspace |
|---|---|---|
Read (OData, tables) | 120/min | 240/min |
Free-form SQL (query) | 60/min | 120/min |
- Exceeded →
429withRetry-After: 60. - Limiter unavailable →
503withRetry-After: 60(fail-closed). - The API buckets are separate from native BI — external consumption doesn't degrade the platform.
Pagination#
REST (/api/v1/tables/{dataset}/{table}): via limit/offset.
limitdefault 100, maximum 1000;offsetis the starting offset.- The response includes
nextOffset(ornullat the end).
OData (server-driven):
- Pages of up to 1,000 rows with
@odata.nextLink; follow the link exactly (it carries an opaque$skiptoken). Tampered token →400. Prefer: odata.maxpagesize=Nshrinks the page (ceiling 1,000); responds withPreference-Applied.- Maximum depth: 1,000,000 rows per query; above that →
400telling you to filter (each page scans the entire table in the datalake).
Idempotency#
- The entire API is read-only — there is no write endpoint.
GETrequests (andPOST /query, which only sends aSELECT) are idempotent by nature: repeating the call doesn't change state. - Identical queries (same workspace version) are served from cache at R$ 0 cost; invalidation by pipeline/DML ensures stale data is never served.
- There is no
Idempotency-Keyheader today (not needed without writes). An idempotency mechanism for write operations would only exist alongside a future write API (Roadmap).
Webhooks#
- There is currently no public webhook subscription API (workspace
events sent to your endpoint) — it's on the
Roadmap. - To react to data changes today, use polling of the OData feed (e.g., incremental refresh in Power BI) or the product's own subscriptions/alerts (email/WhatsApp, depending on the plan).
- The webhook endpoints that exist on the platform are internal inputs for billing/marketing integrations, not a developer API.
Cost#
- Only row extraction costs money; authenticating, listing tables, and reading
$metadatadon't trigger a paid job. The amount inx-ingestia-cost-brlis a projection. LIMIT/OFFSET/pagination do not reduce bytes read in the datalake — filter and aggregate to pay less.
Security#
- Workspace scope on every route; PII kept out of the API; read-only.
- Errors never leak credentials or another workspace's SQL;
404on a nonexistent EntitySet prevents enumeration.
Limits (summary)#
- REST page: max 1000 rows; OData page: max 1000; OData depth: max 1,000,000 rows/query.
- Rate limit as in the table above.
- No write API; no public webhooks; workspace-level key.
Troubleshooting#
| Symptom | Likely cause | What to do |
|---|---|---|
402 | workspace overdue/suspended | settle the payment in the app |
429 | rate limit | respect Retry-After; reduce parallelism |
503 with Retry-After | limiter unavailable or datalake not provisioned | wait and retry; confirm provisioning |
501 (OData) | operation outside the subset | simplify the filter (see OData) |
400 on pagination | went past the 1M-row ceiling or invalid $skiptoken | filter the data; follow @odata.nextLink |
Next steps: Query API · OData/Power BI · Troubleshooting.