Errors

The REST API answers every error as RFC 9457 problem details with Content-Type: application/problem+json. Decide by the status: retry 429 and 503 after Retry-After, fix the request for every other 4xx.

Error bodyCopy Anchor Link

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Send a personal API key or an OAuth access token as a Bearer token.",
  "instance": "/api/v1/projects"
}

Error bodies carry the same security headers as successful ones.

Status codesCopy Anchor Link

The two 401 answers to a token that was sent and refused also come with WWW-Authenticate: Bearer realm="api", error="invalid_token", error_description="…", where the description repeats detail.

Validation errorsCopy Anchor Link

A 422 names each parameter it refuses in errors, with the reason. A closed set of values is listed in the message:

curl -G https://app.mirafive.io/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/overview \
  -H "Authorization: Bearer $MIRAFIVE_API_KEY" \
  --data-urlencode 'period=forever' \
  --data-urlencode 'filters[0][field]=country' \
  --data-urlencode 'filters[0][op]=gt' \
  --data-urlencode 'filters[0][value]=DE'

{
  "type": "about:blank",
  "title": "Unprocessable Content",
  "status": 422,
  "detail": "The request has invalid parameters.",
  "instance": "/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/overview",
  "errors": {
    "period": ["The period must be one of: 1h, 24h, 7d, 30d, 90d, 12m, custom."],
    "filters.0.op": ["This field cannot be compared that way."]
  }
}

Messages you meet most:

Query too largeCopy Anchor Link

{
  "type": "https://docs.mirafive.io/docs/api#query-too-large",
  "title": "Query too large",
  "status": 422,
  "detail": "This question reads more data than one request may. Shorten the period or narrow it with filters.",
  "instance": "/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/overview"
}

Each request may read a limited amount of data. A long period over a busy project, or a filter that has to read many events, can pass it. Sending the same request again gets the same answer. Ask for less instead:

• Shorten the period, for example 90d instead of 12m, or split a long custom range into shorter ones. Counts of events add up across ranges; counts of people do not.
• Add filters that narrow the events early: event_name, page_path, country.
• On People, leave out window=all and sort=first_seen or sort=value, which read each person's whole history.

Warehouse unavailableCopy Anchor Link

{
  "type": "https://docs.mirafive.io/docs/api#warehouse-unavailable",
  "title": "Analytics unavailable",
  "status": 503,
  "detail": "The analytics warehouse did not answer. Try again shortly.",
  "instance": "/api/v1/projects/01932c4e-8a7b-7c3d-9e2f-4b5a6c7d8e9f/overview"
}

The store that holds events did not answer. Nothing is wrong with your request. The answer carries Retry-After: 30: wait that many seconds and send it again. Endpoints that do not read events, such as the projects list, keep working.

Retry policyCopy Anchor Link

• Retry 429 and 503 after the Retry-After seconds. Retry 500 and network errors with a growing delay, for example 1, 2, 4 and 8 seconds.
• Do not retry any other 4xx. The same request gets the same answer.
• Every request only reads, so a retry never changes anything.