Skip to main content
Developer DocumentationCertify and Publish Your DeviceSmartThings APIEnterprise API
Developer Documentation
SmartThings API updates are on the way!
Preview the upcoming API Access Apps experience here, but note that some features described in this section are coming soon. Visit the SmartThings blog to learn more.

Troubleshoot Common Errors

While creating your API Access App, you may encounter a few common roadblocks related to authentication, permissions, or webhook configurations. Review the following scenarios to quickly diagnose and resolve these issues.

401 Unauthorized​

Expired or Invalid Tokens

Symptom: Your API requests are suddenly failing with a 401 Unauthorized HTTP status code.

Solution: The access token obtained during the OAuth flow has a limited lifetime (typically 24 hours). After expiry, any API request using that token returns a 401 Unauthorized response. Implement a refresh strategy to obtain a new access token using your stored refresh token. Consider proactively refreshing tokens before they expire based on the expires_in value.

Missing Devices or Failed Commands​

Scope Issues

Symptom: Your app cannot see certain devices in the user's location, or attempts to send a command fail.

Solution: Your application only has access to the devices and actions explicitly granted to it during the OAuth 2.0 process. Verify that you requested the correct scopes during setup. Note that reading devices requires r:devices, while controlling devices requires an explicit x:devices scope.

429 Too Many Requests​

Rate Limiting

Symptom: Your application receives a 429 Too Many Requests response.

Solution: SmartThings enforces rate limits on API calls, which vary by endpoint and payment plan. Check the x-ratelimit-reset response header to determine how many seconds remain until the rate limit window resets. Implement backoff logic in your application to pause requests until the reset period has passed.

API Subscription Missing or Usage Limit Reached​

Payment Required

Symptom: When you call a paid SmartThings API feature, you may get a 402 Payment Required response. This happens when your payment has lapsed, your subscription no longer exists, or your usage has gone over your plan's limits. Your access token can still be valid when this happens.

Solution: Sign in to the SmartThings Developer Console and review your plan details. Check that you have an active, qualifying plan and that your current usage is within your plan's quotas. Once that's sorted, your API calls should work again. Don't retry 402 responses in a loop. Pause requests from the affected app until the plan is fixed.

Webhook Delivery Failures and Disabled Subscriptions​

Symptom: Your app stops receiving device events, or SmartThings unexpectedly disables your active subscriptions.

Solution: SmartThings requires your webhook endpoint to properly acknowledge every event payload. Your app must respond with a 200 OK status code to acknowledge receipt of webhook events. If your app does not respond with a 200 status code, SmartThings may retry the delivery and could eventually disable the subscription entirely. Ensure your app correctly verifies the HTTP Signature in the authorization header; otherwise, your app might be erroneously rejecting legitimate SmartThings traffic. Verification failures are often caused by using the wrong public key for the request's keyId. See Verify a Request and Retrieve the Public Key.

OAuth Callback Failures​

State Mismatch or Access Denied

Symptom: The OAuth authorization flow fails when SmartThings redirects the user back to your GET /oauth/callback endpoint.

Solution: This typically occurs due to security validations or user actions during the authorization prompt. State Mismatch: Verify that the state parameter in the callback matches the exact value you stored in the user's session. If it does not match, you must reject the request to prevent CSRF attacks. Access Denied: If the user clicks "Deny" on the SmartThings authorization page, you will receive an error=access_denied parameter instead of a code. Check for this parameter and display a graceful error message in your UI rather than attempting a token exchange.