OneAnalytics docs

API errors

OneAnalytics returns errors as application/problem+json per RFC 7807. Every error body is a Problem object with stable fields you can branch on.

Shape

{
  "type":     "https://docs.analytics.rstglobal.in/api/errors#share-expired",
  "title":    "Sharing grant expired",
  "status":   403,
  "detail":   "The share link expired on 2026-04-01 and has been tombstoned.",
  "instance": "/v1/sharing/grants/grt_01H...",
  "code":     "share/expired",
  "trace_id": "4f8a2c...",
  "doc_url":  "https://docs.analytics.rstglobal.in/api/errors#share-expired"
}
  • code — stable, dotted, kebab — branch on this, never on title or detail.
  • trace_id — attach to support tickets; we can look up the full request trace.
  • doc_url — deep-links into this page.

Stable codes

Authentication & authorisation

  • auth/missing-token (401) — No Authorization header.
  • auth/invalid-token (401) — Token signature/format invalid.
  • auth/expired-token (401) — Token was valid but is past exp.
  • auth/scope-denied (403) — Token lacks the required OAuth scope.
  • auth/tenant-mismatch (403) — Token is for a different tenant.

Resource

  • resource/not-found (404) — ID doesn't resolve in your tenant.
  • resource/gone (410) — Resource existed but was deleted; see tombstoned_at.
  • resource/conflict (409) — Unique constraint, e.g., workspace name taken.
  • resource/precondition-failed (412) — If-Match ETag didn't match.

Sharing

  • share/expired (403) — Grant exists but expires_at is in the past.
  • share/password-required (401) — Link has a password; include X-Share-Password.
  • share/password-incorrect (401) — Wrong password.
  • share/principal-mismatch (403) — Grant is for a user/team you aren't in.

Query & dataset

  • dataset/not-refreshed (409) — Never completed a refresh; no data to query.
  • dataset/refresh-in-progress (503) — A refresh is running; retry with backoff.
  • query/invalid-semantic (400) — Referenced dimension/measure doesn't exist.
  • query/timeout (504) — Query exceeded the dataset's timeout.
  • query/too-many-rows (413) — Result set exceeds limit; use pagination.

Rate limiting

  • rate-limit/burst (429) — Short-window (1 min) bucket exhausted; Retry-After: <seconds>.
  • rate-limit/sustained (429) — Sliding-window (1 hour) budget exhausted.

Billing

  • billing/plan-required (402) — Feature requires Growth or higher.
  • billing/quota-exceeded (402) — Storage, refresh, or user quota hit.

Retry guidance

  • 5xx — Retry with exponential backoff (jitter). All our 5xx responses are safe to retry with the same Idempotency-Key.
  • 429 — Respect Retry-After.
  • 4xx — Do not retry; fix the request.

Problem type URIs

The type field is a URL pointing to this page with a hash fragment equal to the code. Following it takes the reader to the relevant section.