Error codes

Every 4xx / 5xx response shares the same envelope. Match on the machine-readable code field for programmatic handling; show message to humans.

01Error envelope

Consistent shape across all endpoints.

error.json

{
  "error": {
    "code": "invalid_stage",
    "message": "`stage` must be one of aware, acquire, activate, retain, revenue, refer",
    "request_id": "req_01HWA9Q8M4",
    "details": [
      { "field": "stage", "got": "aquire" }
    ]
  }
}

The request_id is the key field when contacting support. Include it in any bug report — it links to the full server-side trace.

02Error catalog

Complete list of codes, by HTTP status.

Status	Code	When
400	`invalid_stage`	The `stage` value is not one of the six AAARRR keys (`aware`, `acquire`, `activate`, `retain`, `revenue`, `refer`).
400	`invalid_window`	`window` must be one of `7d`, `30d`, `90d`.
400	`validation_failed`	A field in the request body failed validation. See the `details` array.
400	`invalid_filter`	A `q[...]` filter references a field that's not in the whitelist for this endpoint.
401	`invalid_token`	Missing or malformed `Authorization` header.
401	`token_revoked`	The token exists but has been revoked. Create a new one.
403	`project_forbidden`	The token belongs to a different project than the resource you're trying to access.
404	`session_not_found`	No session matches the given id, or it has been purged by retention policy.
404	`cohort_not_found`	The supplied cohort id does not exist in this workspace.
413	`payload_too_large`	Batch exceeds 100 events or 1 MB total.
429	`rate_limited`	Over 600 req/min. Retry after the seconds in the `Retry-After` header.

03Retry strategy

How to recover — by status class.

4xx (except 429) — do not retry. Fix the request.
429 — retry after the seconds in Retry-After. Use exponential backoff if you hit the limit repeatedly.
5xx — retry with backoff (start 1s, double up to 60s). If it persists past 5 minutes, check status.sumidata.io.

04Error Impact report

Which captured errors block purchases — ranked in the dashboard.

Browser errors captured by the SDK feed the Error Impact report. It splits the sessions where each error group appeared into bought vs. didn't buy, compares each group's conversion against your site baseline, and ranks groups by the estimated purchases lost — so the most revenue-damaging bugs surface first. Groups seen in fewer than 20 sessions are held below a reliability threshold rather than ranked, and the errors-vs-sales correlation shown on the chart is a prioritization indicator, not proof of cause. Matching purchases to sessions requires the session link on conversion events — see Conversions.