Rate Limits

Introduction

We are introducing rate limits to the Authentication endpoint of the SmartBuildings API. This is designed to ensure our API remains stable and available for you and all other users.

Frequently Asked Questions

Question	Answer
What is the rate limit?	The rate limit will programmatically enforce that your app is not able to generate more than 120 access tokens via the POST /token endpoint in every 2 hour period. The rate limit is enforced on the client-level, not IP address.
How did you pick this rate limit?	In the SmartBuildings API, you really only need to generate one access token for all your API activity. Access tokens can be reused until they expire after two hours. This rate limit kicks in when you generate more than 1 access token per minute, which we believe is improper use of the API. We strongly advice auditing your systems to reuse access tokens, because in the future, the rate limit may be updated to allow fewer than 120 API calls every 2 hours.
Rate limits on other endpoints?	We are starting out with implementing rate limits on the POST /token endpoint only. We do not have an ETA for when it will be rolled out to other endpoints yet, but it is on the product roadmap.
What error will I receive if my app goes over the rate limit?	If your app exceeds this rate limit, then you'll get a 429 status code, with the following response body: The JSON response body will be: `{ error: "rate_limit_exceeded" error_description: "Token rate limit exceeded, please try again later" }` When your app is rate limited, you won’t be able to generate new access tokens, however all existing access tokens generated within the past 2 hours will continue to work until expiry. The rate limit only prevents you from generating new access tokens, without prohibiting activity on any other endpoints with a pre-existing valid access token.
When will the rate limit block be lifted?	Rate limit is enforced in two hour blocks. You can see when it will reset by monitoring the x-token-rate-limit-reset response header. The header value is in Epoc time.
What new response headers are being added to the API?	`x-token-ratelimit-limit` - total API requests allowed before rate limit prevents further access `x-token-ratelimit-remaining` - API requests remaining before rate limit will be enforced `x-token-ratelimit-reset` - the timestamp representing when the rate limit will be reset in Epoch time
Will be the response header values perfectly accurate?	No. We can not guarantee that rate limit response header values will be perfectly accurate. However they will be in the ballpark to be a reliable metric to track and inform decisions.

tl;dr

An access token is valid for 2 hours. You should only generate one access token and re-use it for all your API calls until it expires in 2 hours. The rate limit will programmatically prevent you from generate another access token when you already generated 120+ access tokens in the last 2 hours.