> For the complete documentation index, see [llms.txt](https://docs.butlr.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.butlr.io/integrations-api-third-party-sensors/reporting-api/errors.md).

# Errors

Errors return a non-`200` status and an `errors` array. `data` is omitted.

```json
{
  "errors": [
    { "code": -5003, "description": "items is required and must not be empty" },
    { "code": -5009, "description": "interval is required" }
  ]
}
```

* **Reported together:** validation problems are reported together, except that the range and `fill_gaps` checks only run once `interval` is valid. Fixing an interval error can reveal a new error.
* **Timeouts:** a query that runs too long can instead end with a `504` from the load balancer, with no `errors` body. Narrow the request if that happens.

## Error codes

| Code    | HTTP | Meaning                                                                                                                                                                                                                                    |
| ------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `-2`    | 400  | Access token is malformed                                                                                                                                                                                                                  |
| `-3`    | 401  | Access token missing, expired, or not accepted                                                                                                                                                                                             |
| `-5000` | 400  | Body could not be read. Send JSON with `Content-Type: application/json`; an empty or form-encoded body is read as an empty request and gets the "required" errors instead.                                                                 |
| `-5001` | 400  | `measurements` is empty or has a duplicate                                                                                                                                                                                                 |
| `-5002` | 400  | Unknown measurement                                                                                                                                                                                                                        |
| `-5003` | 400  | `items` is empty                                                                                                                                                                                                                           |
| `-5004` | 400  | Item or excluded item has an unrecognized prefix                                                                                                                                                                                           |
| `-5005` | 400  | Item or excluded item contains a disallowed character                                                                                                                                                                                      |
| `-5006` | 400  | `start` is missing or not a valid time                                                                                                                                                                                                     |
| `-5007` | 400  | `stop` is missing or not a valid time                                                                                                                                                                                                      |
| `-5008` | 400  | `start` is not before `stop`                                                                                                                                                                                                               |
| `-5009` | 400  | `interval` is missing, unknown, or not supported by a requested measurement (one error per measurement)                                                                                                                                    |
| `-5010` | 400  | `timezone` is not a valid IANA time zone                                                                                                                                                                                                   |
| `-5011` | 400  | More than 500 `items` or `exclude_items`                                                                                                                                                                                                   |
| `-5012` | 400  | Time range too long for the interval or measurement, or reaches past event history. See [Query Limits](/integrations-api-third-party-sensors/reporting-api/query-limits.md).                                                               |
| `-5013` | 400  | `fill_gaps` used with `interval: "1m"`                                                                                                                                                                                                     |
| `-5014` | 400  | More than 50 `fields`                                                                                                                                                                                                                      |
| `-5015` | 400  | `fill_gaps` used with an event measurement                                                                                                                                                                                                 |
| `-5016` | 400  | Result too large (over 1,000,000 rows for one measurement in one storage tier). Narrow the range or items, or use a coarser interval.                                                                                                      |
| `-5100` | 401  | Token data missing                                                                                                                                                                                                                         |
| `-5101` | 401  | Token data invalid                                                                                                                                                                                                                         |
| `-5102` | 400  | The access token carries no usable client ID                                                                                                                                                                                               |
| `-5200` | 429  | [Rate limit](/integrations-api-third-party-sensors/authentication.md#rate-limits) exceeded. Retry after the `Retry-After` header.                                                                                                          |
| `-5300` | 500  | The query failed. Retry once; if it keeps failing, check that your [item prefixes](/integrations-api-third-party-sensors/reporting-api/items-and-fields.md#use-a-prefix-at-or-above-the-measurements-level) match the measurement's level. |
| `-5500` | 503  | Reporting is temporarily unavailable                                                                                                                                                                                                       |
| `-5501` | 503  | Data for a requested measurement is temporarily unavailable                                                                                                                                                                                |