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
Guardrail50Max 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
Guardrail20Maximum 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

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