Descope Rate Limiting
This guide outlines how Descope enforces rate limits across its APIs and SDKs, ensuring efficient usage of resources. Below, you'll find detailed information about the various rate limits Descope has implemented, along with best practices to avoid exceeding these limits and ensure optimal performance.
Note
When you're SDK or API calls are rate limited by Descope, you will receive a 429 HTTP status code. Review Rate Limit Best Practices for next steps when you start to be rate limited.
Rate Limit Calculations
Descope calculates the rate limit based on IP address for most operations; however, rate limits for user management calls are limited based on project ID.
User Management Limits
Descope rate limits specific user management paths with lower limits than the generalized limits.
The paths below are limited to 100 requests per 60 seconds, with a 60-second backoff, whether initiated from the SDK or API.
/v1/mgmt/user/create/v1/mgmt/user/create/batch
The paths below are limited to 200 requests per 60 seconds, with a 60-second backoff, whether initiated from the SDK or API.
/v1/mgmt/user/update/v1/mgmt/user/search
Backend API and SDK Limits
Descope SDKs
Backend
The Descope backend SDK rate is limited to 1000 requests per 10 seconds, with a 10-second backoff for non-authentication-related tasks. Note that management-related tasks have stricter rate limits, which can be found within the above rate limit outline for user management.
Frontend
The Descope frontend SDKs are rate-limited at a lower value; the rate limit is 100 requests per 60 seconds with a 60-second backoff.
Descope API
Descope's API rate limits all traffic to 100 requests per 60 seconds with a 60-second backoff, excluding paths with a higher rate limit for user management.
Excluded Endpoints
Outside of the abovementioned rate limits, the following paths have an enhanced limit, whether from API or SDK. The rate limit of the paths below is 1000 requests per 10 seconds with a 10-second backoff.
/scim/*/.well-known/*
Rate Limit Best Practices
Monitor and Backoff
With all API and SDK usage, one must protect themselves from rate limiting. It is advised to build rate
limit error handling within your application to abide by the rate limits set in place by Descope.
Monitor for the 429 responses code and implement a backoff as defined above-outlined backoffs.
Review Utilization
If you frequently hit a rate limit scenario, it is recommended that you review how you utilize the endpoints that are rate-limiting you.
To review your Descope API and SDK usage, review the API URI that you are hitting the rate limit or which SDK calls you are hitting the rate limit. Once you have identified these paths, review where these calls are frequently utilized in your application.
Once you have found where these calls are being made within your application, review them for consolidation. For example, if you're doing multiple user updates in sequence, switch to a patch or update call to consolidate these calls.
Note
Some common cases misuse the Descope API and SDK. For example, you frequently load a user for a specific user detail, such as their email address or custom attribute.
In that case, you can save execution time and additional API/SDK calls to load the user by adding the items to the custom claim. See this documentation for details on adding items to the custom claims.
Session Validation
If you are experiencing rate limits within Descope on the session validation endpoints, you may be manually validating the sessions within your application. Manually validating the user's session is not required as the SDKs cache the Descope public keys to validate the session to prevent hitting these rate limits. Rather than explicitly calling the Descope API to validate the session, you can depend on the Descope SDK to validate this for you.
Inquire with Descope Support
If you are hitting rate limits within your application and are unable to determine how to best accommodate your use case without hitting the rate limit, feel free to reach out to the Descope team for assistance.