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

# Errors

> Error response format and HTTP status codes returned by the API

The API uses conventional HTTP status codes to indicate the result of a request.
Codes in the `2xx` range indicate success, `4xx` codes indicate a problem with
the request (for example a missing parameter or insufficient permissions), and
`5xx` codes indicate an unexpected error on the server.

## Error response shape

Every error response has the same JSON body: a single `message` field with a
human-readable explanation.

```json theme={null}
{
  "message": "Resource not found"
}
```

| Field     | Type     | Description                             |
| --------- | -------- | --------------------------------------- |
| `message` | `string` | Human-readable description of the issue |

## Status codes

| Status | Meaning               | Typical cause                                                                   |
| ------ | --------------------- | ------------------------------------------------------------------------------- |
| `400`  | Bad Request           | The request body or query parameters failed validation.                         |
| `401`  | Unauthorized          | The `x-api-key` header is missing, invalid, or the token has expired.           |
| `403`  | Forbidden             | The token is valid but does not have access to the requested resource.          |
| `404`  | Not Found             | The resource does not exist, or the token cannot access it.                     |
| `409`  | Conflict              | The request conflicts with existing data (for example a uniqueness constraint). |
| `422`  | Unprocessable Content | The request is valid but too expensive to fulfil within the server time limit.  |
| `500`  | Internal Server Error | An unexpected error occurred on the server.                                     |

## Handling errors

Whether a request is worth retrying depends on the status code:

* **`400`, `403`, `404`, `409`, `422`** - retrying the identical request will
  not succeed. Change the request (fix the input, adjust scope, or use a token
  with the right permissions) before resending.
* **`401`** - check the `x-api-key` header and that the token has not expired.
* **`500`** - usually transient. Retry with exponential backoff; if it persists,
  contact support.

### Query too expensive (`422`)

The [Fetch sensor data](/api-reference/fetch-sensor-data) endpoint can return
`422` when a query is too broad to complete within the server's time limit,
typically a wide or unbounded time range combined with many parameters or
devices. To resolve it:

* Narrow the time range (provided by `startDate` and `endDate`).
* Reduce the number of parameters, devices, or sensors in a single request.
* Apply an `aggregation` interval to downsample the result.