# 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.

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](/docs/billing/overage)) |
| 426 | `app_update_required` | Only for the [mobile app](/docs/dashboard/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](/docs/api/rate-limits)) |
| 5xx | Any | Our fault. Retry with backoff and check the [status page](/status) |

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

One code only appears over [MCP](/docs/mcp#actions-for-a-person):
`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.
