Add handling for API Rate limit error (#121)

* Add handling for API Rate limit error

* extract raise rate limit exception logic to function

* update pre-commit file with newer poetry version + update poetry lock file with latest changes

* update poetry version in docker file

* update the error message key

* update tests with the new name

* raise RateLimit exception also when validating token + update Readme file

* set the reference url to be markdown link

Author: guyp-descope

.pre-commit-config.yaml

@@ -29,7 +29,7 @@ repos:
     hooks:
       - id: flake8
   - repo: https://github.com/python-poetry/poetry
-    rev: 1.2.1 # add version here
+    rev: 1.3.2 # add version here
     hooks:
       - id: poetry-check
       - id: poetry-lock

Dockerfile

@@ -23,7 +23,7 @@ RUN apt-get update \
         git
 
 # Install Poetry - respects $POETRY_VERSION & $POETRY_HOME
-ENV POETRY_VERSION=1.2.0
+ENV POETRY_VERSION=1.3.2
 RUN curl -sSL https://install.python-poetry.org | python
 
 # We copy our Python requirements here to cache them

README.md

@@ -615,6 +615,23 @@ updated_jwt = client.mgmt.jwt.updateJWT(
 )
 ```
 
+## API Rate limits
+
+Handle API rate limits by comparing the exception to the APIRateLimitExceeded exception, which includes the RateLimitParameters map with the key "Retry-After." This key indicates how many seconds until the next valid API call can take place. More information on Descope's rate limit is covered here: [Descope rate limit reference page](https://docs.descope.com/rate-limit)
+
+```python
+try:
+    descope_client.magiclink.sign_up_or_in(
+        method=DeliveryMethod.EMAIL,
+        login_id="[email protected]",
+        uri="http://myapp.com/verify-magic-link",
+    )
+except RateLimitException as e:
+    retry_after_seconds = e.rate_limit_parameters.get(API_RATE_LIMIT_RETRY_AFTER_HEADER)
+    # This variable indicates how many seconds until the next valid API call can take place.
+```
+
+
 ## Code Samples
 
 You can find various usage samples in the [samples folder](https://github.com/descope/python-sdk/blob/main/samples).

descope/__init__.py

@@ -7,6 +7,11 @@
     DeliveryMethod,
 )
 from descope.descope_client import DescopeClient
-from descope.exceptions import AuthException
+from descope.exceptions import (
+    API_RATE_LIMIT_RETRY_AFTER_HEADER,
+    ERROR_TYPE_API_RATE_LIMIT,
+    AuthException,
+    RateLimitException,
+)
 from descope.management.common import AssociatedTenant
 from descope.management.sso_settings import AttributeMapping, RoleMapping

descope/auth.py

@@ -22,11 +22,14 @@
     EndpointsV2,
 )
 from descope.exceptions import (
+    API_RATE_LIMIT_RETRY_AFTER_HEADER,
+    ERROR_TYPE_API_RATE_LIMIT,
     ERROR_TYPE_INVALID_ARGUMENT,
     ERROR_TYPE_INVALID_PUBLIC_KEY,
     ERROR_TYPE_INVALID_TOKEN,
     ERROR_TYPE_SERVER_ERROR,
     AuthException,
+    RateLimitException,
 )
 
 
@@ -73,6 +76,20 @@ def __init__(
                 kid, pub_key, alg = self._validate_and_load_public_key(public_key)
                 self.public_keys = {kid: (pub_key, alg)}
 
+    def _raise_rate_limit_exception(self, response):
+        resp = response.json()
+        raise RateLimitException(
+            resp.get("errorCode", "429"),
+            ERROR_TYPE_API_RATE_LIMIT,
+            resp.get("errorDescription", ""),
+            resp.get("errorMessage", ""),
+            rate_limit_parameters={
+                API_RATE_LIMIT_RETRY_AFTER_HEADER: int(
+                    response.headers.get(API_RATE_LIMIT_RETRY_AFTER_HEADER, 0)
+                )
+            },
+        )
+
     def do_get(
         self,
         uri: str,
@@ -88,6 +105,8 @@ def do_get(
             verify=self.secure,
         )
         if not response.ok:
+            if response.status_code == 429:
+                self._raise_rate_limit_exception(response)  # Raise RateLimitException
             raise AuthException(
                 response.status_code, ERROR_TYPE_SERVER_ERROR, response.text
             )
@@ -105,6 +124,9 @@ def do_post(
             params=params,
         )
         if not response.ok:
+            if response.status_code == 429:
+                self._raise_rate_limit_exception(response)  # Raise RateLimitException
+
             raise AuthException(
                 response.status_code, ERROR_TYPE_SERVER_ERROR, response.text
             )
@@ -296,6 +318,8 @@ def _fetch_public_keys(self) -> None:
         )
 
         if not response.ok:
+            if response.status_code == 429:
+                self._raise_rate_limit_exception(response)  # Raise RateLimitException
             raise AuthException(
                 response.status_code,
                 ERROR_TYPE_SERVER_ERROR,
@@ -485,6 +509,8 @@ def validate_session(self, session_token: str) -> dict:
         try:
             res = self._validate_token(session_token)
             return self.adjust_properties(res, True)
+        except RateLimitException as e:
+            raise e
         except Exception as e:
             raise AuthException(
                 401, ERROR_TYPE_INVALID_TOKEN, f"Invalid session token: {e}"
@@ -500,6 +526,8 @@ def refresh_session(self, refresh_token: str) -> dict:
 
         try:
             self._validate_token(refresh_token)
+        except RateLimitException as e:
+            raise e
         except Exception as e:
             # Refresh is invalid
             raise AuthException(

descope/exceptions.py

@@ -2,6 +2,9 @@
 ERROR_TYPE_SERVER_ERROR = "server error"
 ERROR_TYPE_INVALID_PUBLIC_KEY = "invalid public key"
 ERROR_TYPE_INVALID_TOKEN = "invalid token"
+ERROR_TYPE_API_RATE_LIMIT = "API rate limit exceeded"
+
+API_RATE_LIMIT_RETRY_AFTER_HEADER = "Retry-After"
 
 
 class AuthException(Exception):
@@ -21,3 +24,26 @@ def __repr__(self):
 
     def __str__(self):
         return str(self.__dict__)
+
+
+class RateLimitException(Exception):
+    def __init__(
+        self,
+        status_code: int = None,
+        error_type: str = None,
+        error_description: str = None,
+        error_message: str = None,
+        rate_limit_parameters: dict = {},
+        **kwargs,
+    ):
+        self.status_code = status_code
+        self.error_type = error_type
+        self.error_description = error_description
+        self.error_message = error_message
+        self.rate_limit_parameters = rate_limit_parameters
+
+    def __repr__(self):
+        return f"Error {self.__dict__}"
+
+    def __str__(self):
+        return str(self.__dict__)