Skip to main content
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. 
{
  "message": "Resource not found"
}
FieldTypeDescription
messagestringHuman-readable description of the issue

​
Status codes

StatusMeaningTypical cause
400Bad RequestThe request body or query parameters failed validation.
401UnauthorizedThe x-api-key header is missing, invalid, or the token has expired.
403ForbiddenThe token is valid but does not have access to the requested resource.
404Not FoundThe resource does not exist, or the token cannot access it.
409ConflictThe request conflicts with existing data (for example a uniqueness constraint).
422Unprocessable ContentThe request is valid but too expensive to fulfil within the server time limit.
500Internal Server ErrorAn 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 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.