Rate limit types

Airthings for Business API clients are restricted by two rate limits with two different purposes. The first one being the IP-based rate limit, which has the purpose of protecting our service from attacks, and the second one being the client-based rate limit which is meant to reduce potential misuse of the service.

IP-based rate limit

The IP-based rate limit restricts the amount of successful requests a single IP can make to the API during a 5 minute period. If one IP exceeds 2 000 requests in a period of 5 minutes, it will receive a response with the status code: 429, and is restricted until that 5 minute period has passed. The IP is then allowed an additional 2 000 requests for the next 5 minutes, and so on.

If an IP is continuously breaching this limit, it will be permanently blocked from making any new requests to the API.

This limit is static, and can't be increased.

Client-based rate limit

Each Airthings For Business API Client is by default allowed 5 000 requests per hour. Users signed in through the same client all share that same quota since the client and subscription is owned by the account where the client is configured.

The current rate limit status is indicated in the response headers:

X-RateLimit-Reset: 1607336100   // The time at which the current rate limit window resets (UTC epoch seconds).
X-RateLimit-Remaining: 1000     // The number of remaining requests in the current rate limit window.
X-RateLimit-Limit: 5000         // The maximum number of requests you're granted per hour.

If a client exceeds the rate limit, the API will respond with status code: 429, and the response body and header below will describe when new successful requests can be made to the API.

X-RateLimit-Retry-After: 100    // A new request can be performed after this many seconds.

{
    "error": "TOO_MANY_REQUESTS",
    "error_description": "Rate limit on API exceeded"
}

Best practice and support

For most clients, the quota of 5000 requests per hour is sufficient, and exceeding it might indicate inefficient use of the API. The most common reason for the limit being exceeded is the devices/{serialNumber}/latest-samples endpoint being used excessively to retrieve sample data from each device in the account. In that case, we recommend reducing the request interval since samples from devices are by default only updated every 5 minutes, and can be configured to a maximum sample rate of 2.5 minutes for some devices.

The best way to increase the efficiency of the integration and reduce the amount of requests is to use the locations/{locationId}/latest-samples endpoint to receive latest samples from devices, as that endpoint will return the latest samples for all devices registered to the selected location in a single response. Also consider using the event-based integrations (Webhooks or MQTT), which will transmit data immediately after it's been processed - that way you won't have to make any requests for the latest samples at all.

If you have any questions or need to increase your client's request quota, please send a request to Airthings For Business Support.