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.

​
Status codes

​
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.
  • 429 - wait for the number of seconds given in the Retry-After header, then retry. See Rate limiting.
  • 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.

​
Rate limiting

Each API token has a rate limit, by default this is 200 requests per minute over a rolling window. These headers are returned in each request: Rejected requests are not counted against your quota. An error message is returned when your rate limit is exceeded:
To stay under the limit:
  • Batch query sensor data by device or multiple parameters into a single Fetch sensor data call rather than one request each.
  • Limit polling rates based on the transmission period of your devices, since sensor data is only updated on a transmission.
If your integration needs a higher limit, contact support with your expected request volume.