Errors & limits

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

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

{
  "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 rather than issuing many single queries in a tight loop.