Rate limits

Rate limits and guardrails apply.

Types of limits

  • Guardrail defines the allowed maximum number of instances.
  • Rate limit defines the limit on the throughput (X requests per unit Y).

See below.

App types

The app types applicable in this document refer to the appType as defined by the APPS API. These app types are as follows:

  • LAMBDA_SMART_APP, and
  • WEBHOOK_SMART_APP

See the APPS API.

Execution

· Apps

Type Limit Description
Guardrail 35 Maximum number of apps per app type per user
100 Maximum number of total apps (active + inactive) per app type per user
Rate limit 60 requests per minute Rate limit on all Apps API unless specified otherwise

· Installed Apps

Type Limit Description
Guardrail 100 Maximum Installs per Location
Rate limit 60 requests per minute Rate limit on all Installed Apps API unless specified otherwise

· Execution

Type Limit Description
Rate limit 20 requests per minute Execution Lifecycles (Per Installed App): EVENT, UPDATE, INSTALL, UNINSTALL, CONFIGURATION, OAUTH CALLBACK, Execute
Execution Lifecycles (Per App Target): PING

· Locations

Type Limit Description
Guardrail 50 Maximum Locations per user
Rate limit 100 requests per minute Get Location, List Location
20 requests per hour Update Location
50 requests per hour Create Location, Delete Location

Event

· Subscriptions

Type Limit Description
Guardrail 20 Maximum number of Subscriptions per Installed app
Rate limit 40 requests per 15 mins Creating Subscriptions
15 requests per 15 mins Rate limit on all Subscriptions API unless specified otherwise

· Schedules

Type Limit Description
Guardrail 6 Maximum Schedules per Installed app
Rate limit 12 requests per minute POST Schedules
20 requests per 6 minutes Rate limit on all Schedules API unless specified otherwise

· Devices

Type Limit Description
Guardrail 10 Commands to a device per request
30 Maximum number of devices per Installed app (cloud-to-cloud)
50 State events per request
Rate limit 12 requests per minute Get State (per device)
Send Commands (per device)
Create State events (per device)
Rate limit on all Devices API unless specified otherwise

· Device Profiles

Type Limit Description
Guardrail 10 Components per device
20 Capabilities per component
100 Profiles per user
Rate limit 15 requests per minute Get device profiles by ID (per ID)
120 requests per minute Rate limit on all Device Profiles API unless specified otherwise

· Scenes

Type Limit Description
Rate limit 50 requests per minute per scene POST Execute Scene
50 requests per minute GET List Scenes

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

On the other hand, 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." }
    ]
  }
}