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.