As has been previously discussed, we have been focussing on the stability and reliability of the SmartThings platform recently. The ability for developers to create their own solutions by authoring SmartApps and Device Handlers is also of utmost importance to us. Since all SmartApps and Device Handlers are currently executed in the SmartThings cloud*, we must ensure that no one SmartApp or Device Handler can negatively impact the overall security or health of the SmartThings platform. It is our priority to provide the most stable platform at any time, while also providing an open platform for community development.
*See the FAQ at the end of this post for information about any impacts to locally executing SmartApps or Device Handlers in hub v2.
SmartApps are typically executed in response to various subscribed-to events. If a SmartApp subscribes to a very large number of particularly “chatty” devices, or creates an infinite loop of events (for example, subscribing to an “on” and “off” event, and the “on” command actually triggers the “off” event and vice versa - leading to a never-ending chain of event handlers being called), it can result in a SmartApp that consumes a disproportionate amount of resources.
To ensure that no one SmartApp can potentially impact the platform, we have limited SmartApps to executing 250 times in 60 seconds. Our analysis shows that this limit impacts a very, very small number of SmartApps, yet will go a long way to ensuring the overall health and stability of the SmartThings platform.
Device Handler Execution
Similar to SmartApps, Device Handlers are also limited to 250 executions in 60 seconds.
Common causes for exceeding this limit are a SmartApp that sends many commands to one device by receiving a large number of event subscriptions (if that doesn’t first hit the limit for SmartApps). For example, DLNA players that are extremely chatty or devices that bind to frequently changing energy/power values may also encounter this limit. Again, our analysis shows that the number of impacted Device Handlers is extremely small.
SmartApp API Execution
SmartApps that expose web APIs through the mappings definition pose another potential resource consumption issue. Frequent calls to such “Web Services SmartApps” may also consume a disproportionately large number of resources.
To protect against this, inbound requests to such SmartApps will be limited to 250 requests in 60 seconds. If the limit is reached, each subsequent HTTP response will have a status code of 429, until the time window starts over. This allows callers to handle these excessive requests as they see fit.
Device Handler API Execution
The same limits and handling of SmartApp API execution limits applies to Device Handlers that expose web APIs using the mapping definition.
Q: When do these limits go into effect?
A: We turned on the SmartApp and Device Handler execution limits last week, in response to various incidents that were negatively impacting overall platform stability. We plan to begin enforcing limits on inbound web API requests to SmartApps and Device Handlers next week. We will follow up here to confirm that this limit has been turned on.
Q: How likely is it that I will be rate limited?
A: Very, very unlikely. We have spent time learning the appropriate limit that would impact a very small number of SmartApps or Device Handlers, while ensuring no single SmartApp or Device Handler can consume excessive resources.
Q: How will I know if my SmartApp or Device Handler is being rate limited?
A: For SmartApp or Device Handler execution limits, there will be messages in the log that the execution limit has been reached. For the SmartApp API and Device Handler API limits, inbound requests exceeding the limit will generate a response with a 429 status code to indicate the limit has been reached. There also will be three HTTP headers on the response which will explain the limit, the current count against that limit, and the amount of time remaining until the current rate limit window expires:
X-RateLimit-Limit: 250 (the number of requests allowed in the time window)
X-RateLimit-Current: 1 (the number of requests received in the current time window)
X-RateLimit-TTL: 58 (amount of seconds remaining until the current rate limit window expires)
Q: What do I do if I am being rate limited?
A: This will vary depending on the particular SmartApp or Device Handler. It will be up to the author to determine the cause for the excessive executions or requests, and to resolve them accordingly to avoid rate limiting.
Q: What about Hub v2? Will there be rate limiting on it?
A: Rate limiting is constrained to the cloud platform only. In Hub v2, if the Device Handler or SmartApp is executing locally, no rate limiting will be enforced. The purpose of rate limiting is to protect shared cloud resources; if executing locally, there is no need to rate limit.
Q: Other than this communication, is this documented anywhere?
A: Yes. The SmartApp Developer’s Guide, Device Handler’s Guide, and Web Services Guide will be updated to include information on rate limiting.