Rate Limits and Guardrails
Rate limits and guardrails apply to actions conducted on the SmartThings Platform.
Types of limits
- Guardrail defines the allowed maximum number of instances.
- Rate limit defines the limit on the throughput (X requests per unit Y).
App types
The app types applicable refer to the appType as defined by the Apps API. These app types include:
LAMBDA_SMART_APPWEBHOOK_SMART_APP
Visit the APPS API documentation for more details.
Execution
Apps
| Type | Limit | Description |
|---|---|---|
| Guardrail | 35 | Max number of apps per app type per user |
| Guardrail | 100 | Max number of total apps (active + inactive) per app type per user |
| Rate limit | 60 requests per minute | Rate limit applies to all Apps APIs unless otherwise stated |
Installed Apps
| Type | Limit | Description |
|---|---|---|
| Guardrail | 100 | Max installs per location |
| Rate limit | 60 requests per minute | Rate limit applies to all Installed Apps APIs unless otherwise stated |
Execution
| Type | Limit | Description |
|---|---|---|
| Rate limit | 20 requests per minute | Execution Lifecycles (Per Installed App): EVENT, UPDATE, INSTALL, UNINSTALL, CONFIGURATION, OAUTH CALLBACK, Execute |
| Rate limit | 20 requests per minute | Execution Lifecycles (Per App Target): PING |
Locations
| Type | Limit | Description |
|---|---|---|
| Guardrail | 10 | Max locations per user |
| Rate limit | 100 requests per minute | Get Location, List Location |
| Rate limit | 20 requests per hour | Update Location |
| Rate limit 50 requests per hour | Create Location, Delete Location |
Rooms
| Type | Limit | Description |
|---|---|---|
| Rate limit | 50 requests per hour | Get Room, List Room, Update Room, Create Room, Delete Room |
Event
Subscriptions
| Type | Limit | Description |
|---|---|---|
| Guardrail | 40 | Maximum number of subscriptions per Installed App |
| Rate limit | 40 requests every 15 minutes | Creating subscriptions |
| Rate limit | 15 requests every 15 minutes | Rate limit applies to all Subscriptions APIs unless otherwise stated |
Event Size
| Type | Limit | Description |
|---|---|---|
| Guardrail | 10Kib | Maximum allowed size of an event emitted to the platform |
Schedules
| Type | Limit | Description |
|---|---|---|
| Guardrail | 6 | Max schedules per Installed App |
| Rate limit | 12 requests per minute | POST schedules |
| Rate limit | 20 requests every 6 minutes | Rate limit on all Schedules APIs unless otherwise stated |
Devices
When you develop a custom device integration, ensure that your device driver emits a device event when the state of a capability changes (e.g. when a switch turns on), so that clients such as the SmartThings mobile app can refresh the state of the device. Device events should be small and must not be used to track the complete state of a device domain. Device events must not contain extraneous data. Devices should generally not emit more than one event per minute, unless their state has changed as a result of user interaction (such as turning a switch on). SmartThings may adjust device events as necessary to support the SmartThings platform.
| Type | Limit | Description |
|---|---|---|
| Guardrail | 10 | Commands to a device per request |
| Guardrail | 30 | Max number of devices per Installed App (Cloud Connected) |
| Guardrail | 50 | State events per request |
| Rate limit | 12 requests per minute | Get state (per device) |
| Rate limit | 12 requests per minute | Send commands (per device) |
| Rate limit | 12 requests per minute | Create state events (per device) |
| Rate limit | 12 requests per minute | Rate limit applies to all Device APIs unless otherwise stated |
Device Profiles
| Type | Limit | Description |
|---|---|---|
| Guardrail | 10 | Components per device |
| Guardrail | 20 | Capabilities per component |
| Guardrail | 100 | Profiles per user |
| Rate limit | 15 request per minute | Get device profiles by ID (per ID) |
| Rate limit | 120 request per minute | Rate limit applies to all Device Profiles API unless otherwise stated |
Location Modes
| Type | Limit | Description |
|---|---|---|
| Rate limit | 100 requests per minute | Get Mode, List Modes, Change Current Mode |
| Rate limit | 200 requests per minute | Get current mode |
| Rate limit | 10 requests per minute | Create mode, update mode |
Scenes
| Type | Limit | Description |
|---|---|---|
| Rate limit | 50 requests per minute per scene | POST execute scene |
| Rate limit | 50 requests per minute | GET list scenes |
Rules
| Type | Limit | Description |
|---|---|---|
| Install limit | 100 | User |
| Install limit | 50 | ISA |
Rate limit headers
With each API request, SmartThings Cloud will return the below response headers to the client application. These response headers will contain the information on the current status of the limits for that client application:
-
X-RateLimit-Limit: Maximum requests allowed within the rate limit window. -
X-RateLimit-Remaining: Remaining requests available within the window. -
X-RateLimit-Reset: Time in seconds until the current window expires.
Error response
Rate limits
When a client application exceeds the rate limits for a given SmartThings API, the SmartThings API responds with the standard HTTP 429 (Too Many Requests) error code.
Guardrails
When a client application exceeds the guardrail limits for a given SmartThings API, the SmartThings API responds with the standard HTTP 422 (Unprocessable Entity) error code.
The error response from the SmartThings API will contain a JSON response body of the format below:
{
"requestId": "031fec1a-f19f-470a-a7da-710569082846"
"error": {
"code": "ConstraintViolationError",
"message": "Validation errors occurred while process your request.",
"details": [
{ "code": "PatternError", "target": "latitude", "message": "Invalid format." },
{ "code": "SizeError", "target": "name", "message": "Too small." },
{ "code": "SizeError", "target": "description", "message": "Too big." }
]
}
}