> ## Documentation Index
> Fetch the complete documentation index at: https://docs.burthq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Public analytics API error responses and status codes

Errors returned by the analytics endpoints use one stable envelope:

```json theme={null}
{
  "error": {
    "code": "unknown_member",
    "message": "Unknown analytics member.",
    "param": "not_a_member",
    "request_id": "request-id-from-x-request-id"
  }
}
```

`param` is included when a specific request field or member caused the error.
Every matched analytics endpoint response includes `x-request-id`; on errors
it matches `error.request_id`. Unknown paths and unsupported methods return
Fastify's default JSON `404` without this envelope, `x-request-id`, or an
`Allow` header. The service does not currently return `405 Method Not Allowed`.

| HTTP status | Code                 | Meaning                                                                     |
| ----------- | -------------------- | --------------------------------------------------------------------------- |
| 401         | `unauthorized`       | The bearer key is missing, malformed, unknown, or revoked.                  |
| 403         | `insufficient_scope` | The key is valid but does not include `analytics:read`.                     |
| 429         | `rate_limited`       | A rate or admission limit was exceeded. Read `Retry-After`.                 |
| 400         | `invalid_query`      | The JSON body or query grammar is invalid.                                  |
| 400         | `unknown_member`     | A model, metric, dimension, or filter member is not in the catalog.         |
| 400         | `range_too_large`    | The inclusive date range exceeds 366 days.                                  |
| 400         | `invalid_cursor`     | The signed cursor is malformed, tampered with, or does not match the query. |
| 500         | `internal_error`     | An unexpected application or infrastructure failure occurred.               |

The published model names are `agent_runs` and `agent_user_activity`; any
other model name returns `unknown_member`.

A well-formed key that is unknown or revoked normally returns `401`. While the
global credential-verification limit described in
[Authentication](/api/authentication) is exhausted, the same request returns
`429` with `Retry-After` instead. A missing or malformed credential always
returns `401`.

Ordering has two grammar rules, and both violations return `invalid_query`.
Order terms must reference selected members, so ordering by a member that is
not in `metrics` or `dimensions` returns `invalid_query` even when the member
is not in the catalog at all. Order also requires at least one dimension: a
totals query rejects any `order`.

A request with a missing or unsupported `Content-Type`, or with a body larger
than 1 MiB, is also rejected as `400` `invalid_query`.

Body parsing happens before bearer authentication and the custom rate limits.
A malformed query body can therefore return `400` before the same request
would otherwise return `401` or `429`.

Messages for the four query-domain codes are safe for callers. Statement
timeouts and infrastructure failures remain `internal_error`; they are not
converted into query errors.