Docs
Browse the docs

API errors and status codes

The error format of the Privatus Analytics API, every HTTP status and error code (401, 402, 403, 422, 429 and more), and when to retry a failed request.

View as Markdown

Errors always have the same shape:

json 
{
  "error": {
    "code": "validation_failed",
    "message": "Name can't be blank",
    "details": { "name": ["can't be blank"] }
  }
}

details is present for validation errors: field names mapped to messages. Rate-limit responses also carry a Retry-After header (seconds).

Status code When
400 bad_request A request that can't be valid for any operation: a required parameter is missing, or a parameter contains a NUL character
401 unauthorized No token, or an invalid, revoked or expired one
402 plan_limit A plan limit was reached (sites, goals, funnels, members…). The message says which and how to upgrade
403 forbidden Missing permission or site access, the token's IP allowlist, a token used on another workspace, or a suspended account
404 not_found The record doesn't exist or you can't see it
406 not_acceptable The URL is a page of the app with no JSON form (for example a new or edit form)
422 validation_failed Invalid input (see details), including filters that isn't a JSON array
423 locked The workspace's dashboards are locked by Privatus Analytics support. Reaching the monthly limit never locks the API (see Monthly limit)
426 app_update_required Only for the mobile app: the installed version is older than the API still serves
429 rate_limited Too many requests. Wait for the seconds in Retry-After (Rate limits)
5xx Any Our fault. Retry with backoff and check the status page

Handle errors by code, not by message: messages are for people and may change.

One code only appears over MCP: human_only, for a tool whose action is left to a person. Its url is the page of the app where the action is done.

Retrying#

  • GET requests are always safe to retry.
  • Retry 429 after the seconds in its Retry-After header, and 5xx with exponential backoff.
  • Don't retry 4xx other than 429 without changing the request.