# Errors & limits

> The standard error envelope, HTTP status codes, error categories, and rate-limiting behavior of the Flax API.

*[View this page in the Flax docs](https://flax-analytics.com/docs/api-reference/errors-and-limits)*

Every Flax API error is returned with a consistent JSON envelope, so clients can
branch on a stable machine-readable code rather than parsing prose.

## Error envelope

```json
{
  "error": {
    "code": "invalid_argument",
    "message": "measures[0]: unknown measure 'reveune'",
    "category": "validation",
    "requestId": "req_8f3c2a1b"
  }
}
```

| Field | Meaning |
|-------|---------|
| `code` | Stable, machine-readable identifier (e.g. `invalid_argument`, `not_found`, `forbidden`). |
| `message` | Human-readable explanation. Safe to log; never contains raw driver output. |
| `category` | Coarse class: `validation`, `auth`, `not_found`, `rate_limit`, or `internal`. |
| `requestId` | Correlation id — quote it when contacting support. |

## Status codes

| Status | When |
|--------|------|
| `200` / `201` / `202` / `204` | Success. |
| `400` | Malformed request or invalid arguments (`category: validation`). |
| `401` | Missing/invalid token or insufficient scope (`category: auth`). |
| `403` | Authenticated but not permitted for this resource. |
| `404` | Resource does not exist or is not visible to the account. |
| `429` | Rate limited (`category: rate_limit`). |
| `5xx` | Unexpected server error (`category: internal`). |

## Scopes

A `401` with an auth category often means your token lacks the required scope.
Read endpoints need `read`; endpoints that create or modify data need `write`.

## Rate limits

Requests are rate limited per token. When you exceed the limit you receive `429`;
back off and retry. Batch reads with [`/api/query/batch`](/docs/api-reference/queries)
rather than issuing many single queries in a tight loop.

## Related

- [API reference overview](/docs/api-reference/overview)
- [Authentication](/docs/developers/authentication)