Skip to main content

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_APP
  • WEBHOOK_SMART_APP

Visit the APPS API documentation for more details.

Execution

Apps

TypeLimitDescription
Guardrail35Max number of apps per app type per user
Guardrail100Max number of total apps (active + inactive) per app type per user
Rate limit60 requests per minuteRate limit applies to all Apps APIs unless otherwise stated

Installed Apps

TypeLimitDescription
Guardrail100Max installs per location
Rate limit60 requests per minuteRate limit applies to all Installed Apps APIs unless otherwise stated

Execution

TypeLimitDescription
Rate limit20 requests per minuteExecution Lifecycles (Per Installed App): EVENT, UPDATE, INSTALL, UNINSTALL, CONFIGURATION, OAUTH CALLBACK, Execute
Rate limit20 requests per minuteExecution Lifecycles (Per App Target): PING

Locations

TypeLimitDescription
Guardrail10Max locations per user
Rate limit100 requests per minuteGet Location, List Location
Rate limit20 requests per hourUpdate Location
Rate limit 50 requests per hourCreate Location, Delete Location

Rooms

TypeLimitDescription
Rate limit50 requests per hourGet Room, List Room, Update Room, Create Room, Delete Room

Event

Subscriptions

TypeLimitDescription
Guardrail40Maximum number of subscriptions per Installed App
Rate limit40 requests every 15 minutesCreating subscriptions
Rate limit15 requests every 15 minutesRate limit applies to all Subscriptions APIs unless otherwise stated

Schedules

TypeLimitDescription
Guardrail6Max schedules per Installed App
Rate limit12 requests per minutePOST schedules
Rate limit20 requests every 6 minutesRate 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.

TypeLimitDescription
Guardrail10Commands to a device per request
Guardrail30Max number of devices per Installed App (Cloud Connected)
Guardrail50State events per request
Rate limit12 requests per minuteGet state (per device)
Rate limit12 requests per minuteSend commands (per device)
Rate limit12 requests per minuteCreate state events (per device)
Rate limit12 requests per minuteRate limit applies to all Device APIs unless otherwise stated

Device Profiles

TypeLimitDescription
Guardrail10Components per device
Guardrail20Capabilities per component
Guardrail100Profiles per user
Rate limit15 request per minuteGet device profiles by ID (per ID)
Rate limit120 request per minuteRate limit applies to all Device Profiles API unless otherwise stated

Location Modes

TypeLimitDescription
Rate limit100 requests per minuteGet Mode, List Modes, Change Current Mode
Rate limit200 requests per minuteGet current mode
Rate limit10 requests per minuteCreate mode, update mode

Scenes

TypeLimitDescription
Rate limit50 requests per minute per scenePOST execute scene
Rate limit50 requests per minuteGET list scenes

Rules

TypeLimitDescription
Install limit100User
Install limit50ISA

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." }
]
}
}