Skip to content

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

Errors, limits, rate limit, pagination, idempotency, and webhooks

On this page (12)

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) or 403 (insufficient role/scope).

Error format#

Every failure returns JSON with a message in Portuguese and the corresponding HTTP code:

json
{ "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#

CodeMeaningTypical causes
200OKsuccessful read
204No Contentresponse to the OPTIONS preflight (CORS)
400Bad Requestmalformed JSON, missing sql, invalid $skiptoken, pagination beyond the ceiling
401Unauthenticatedmissing, invalid, or revoked key
402Payment Requiredworkspace overdue/suspended — paid extraction blocked
403Forbiddeninsufficient role/scope, non-SELECT SQL, reference outside the workspace/marts
404Not Foundnonexistent OData EntitySet (also protects against enumeration)
429Too Many Requestsrate limit exceeded (includes Retry-After)
501Not ImplementedOData operation outside the supported subset (filter/option)
502Datalake errorfailed to run the query
503Unavailabledatalake not provisioned, own cloud down, or request limiter unavailable (includes Retry-After)

About the limiter 503: the /api/v1 routes 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). Respect Retry-After.

Rate limit#

Limits per 1-minute window, applied per key and per workspace (a leaked key can't exceed the workspace ceiling):

BucketPer keyPer workspace
Read (OData, tables)120/min240/min
Free-form SQL (query)60/min120/min
  • Exceeded → 429 with Retry-After: 60.
  • Limiter unavailable → 503 with Retry-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.

  • limit default 100, maximum 1000; offset is the starting offset.
  • The response includes nextOffset (or null at 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=N shrinks the page (ceiling 1,000); responds with Preference-Applied.
  • Maximum depth: 1,000,000 rows per query; above that → 400 telling you to filter (each page scans the entire table in the datalake).

Idempotency#

  • The entire API is read-only — there is no write endpoint. GET requests (and POST /query, which only sends a SELECT) 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-Key header 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 $metadata don't trigger a paid job. The amount in x-ingestia-cost-brl is 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; 404 on 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#

SymptomLikely causeWhat to do
402workspace overdue/suspendedsettle the payment in the app
429rate limitrespect Retry-After; reduce parallelism
503 with Retry-Afterlimiter unavailable or datalake not provisionedwait and retry; confirm provisioning
501 (OData)operation outside the subsetsimplify the filter (see OData)
400 on paginationwent past the 1M-row ceiling or invalid $skiptokenfilter the data; follow @odata.nextLink

Next steps: Query API · OData/Power BI · Troubleshooting.

Related links