fix(backchannel): expose headers on slow_down errors (HTTP 429s) (#744)

### Changes

In #720, we added the
`headers` field on instances of `Auth0Error`, with the intent to
actually expose the `Retry-After` headers included in backchannel
responses (when the `slow_down` error case is hit). This error case is
actually producing an HTTP 429 status code, which leads to instantiating
a `RateLimitError` instead of an `Auth0Error` (the former was not
adjusted to expose `headers` in the previous PR).

In this PR, I am adding the `headers` field to `RateLimitError` as well
as setting this field when raising this exception.

### References

Please include relevant links supporting this change such as a:

- support ticket
- community post
- StackOverflow post
- support forum thread

### Testing

Please describe how this can be tested by reviewers. Be specific about
anything not tested and reasons why. If this library has unit and/or
integration testing, tests should be added for new functionality and
existing tests should complete without errors.

- [x] This change adds unit test coverage
- [ ] This change adds integration test coverage
- [ ] This change has been tested on the latest version of the
platform/language or why not

### Checklist

- [x] I have read the [Auth0 general contribution
guidelines](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md)
- [x] I have read the [Auth0 Code of
Conduct](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md)
- [x] All existing and new tests complete without errors

Author: adamjmcgrath

auth0/exceptions.py

@@ -23,8 +23,8 @@ def __str__(self) -> str:
 
 
 class RateLimitError(Auth0Error):
-    def __init__(self, error_code: str, message: str, reset_at: int) -> None:
-        super().__init__(status_code=429, error_code=error_code, message=message)
+    def __init__(self, error_code: str, message: str, reset_at: int, headers: Any | None = None) -> None:
+        super().__init__(status_code=429, error_code=error_code, message=message, headers=headers)
         self.reset_at = reset_at
 
 

auth0/rest.py

@@ -289,6 +289,7 @@ def content(self) -> Any:
                     error_code=self._error_code(),
                     message=self._error_message(),
                     reset_at=reset_at,
+                    headers=self._headers,
                 )
             if self._error_code() == "mfa_required":
                 raise Auth0Error(

auth0/test/authentication/test_base.py

@@ -158,6 +158,10 @@ def test_post_rate_limit_error(self, mock_request):
         self.assertEqual(context.exception.message, "desc")
         self.assertIsInstance(context.exception, RateLimitError)
         self.assertEqual(context.exception.reset_at, 9)
+        self.assertIsNotNone(context.exception.headers)
+        self.assertEqual(context.exception.headers["x-ratelimit-limit"], "3")
+        self.assertEqual(context.exception.headers["x-ratelimit-remaining"], "6")
+        self.assertEqual(context.exception.headers["x-ratelimit-reset"], "9")
 
     @mock.patch("requests.request")
     def test_post_rate_limit_error_without_headers(self, mock_request):
@@ -177,6 +181,8 @@ def test_post_rate_limit_error_without_headers(self, mock_request):
         self.assertEqual(context.exception.message, "desc")
         self.assertIsInstance(context.exception, RateLimitError)
         self.assertEqual(context.exception.reset_at, -1)
+        self.assertIsNotNone(context.exception.headers)
+        self.assertEqual(context.exception.headers, {})
 
     @mock.patch("requests.request")
     def test_post_error_with_code_property(self, mock_request):

auth0/test/authentication/test_get_token.py

@@ -6,7 +6,7 @@
 
 from cryptography.hazmat.primitives import asymmetric, serialization
 
-from ... import Auth0Error
+from ...exceptions import RateLimitError
 from ...authentication.get_token import GetToken
 
 
@@ -339,22 +339,22 @@ def test_backchannel_login(self, mock_post):
         )
 
     @mock.patch("requests.request")
-    def test_backchannel_login_headers_on_failure(self, mock_requests_request):
+    def test_backchannel_login_headers_on_slow_down(self, mock_requests_request):
         response = requests.Response()
-        response.status_code = 400
+        response.status_code = 429
         response.headers = {"Retry-After": "100"}
         response._content = b'{"error":"slow_down"}'
         mock_requests_request.return_value = response
 
         g = GetToken("my.domain.com", "cid", client_secret="csec")
 
-        with self.assertRaises(Auth0Error) as context:
+        with self.assertRaises(RateLimitError) as context:
             g.backchannel_login(
                 auth_req_id="reqid",
                 grant_type="urn:openid:params:grant-type:ciba",
             )
         self.assertEqual(context.exception.headers["Retry-After"], "100")
-        self.assertEqual(context.exception.status_code, 400)
+        self.assertEqual(context.exception.status_code, 429)
 
     @mock.patch("auth0.rest.RestClient.post")
     def test_connection_login(self, mock_post):

auth0/test/management/test_rest.py

@@ -278,6 +278,10 @@ def test_get_rate_limit_error(self, mock_request):
         self.assertEqual(context.exception.message, "message")
         self.assertIsInstance(context.exception, RateLimitError)
         self.assertEqual(context.exception.reset_at, 9)
+        self.assertIsNotNone(context.exception.headers)
+        self.assertEqual(context.exception.headers["x-ratelimit-limit"], "3")
+        self.assertEqual(context.exception.headers["x-ratelimit-remaining"], "6")
+        self.assertEqual(context.exception.headers["x-ratelimit-reset"], "9")
 
         self.assertEqual(rc._metrics["retries"], 0)
 
@@ -300,6 +304,8 @@ def test_get_rate_limit_error_without_headers(self, mock_request):
         self.assertEqual(context.exception.message, "message")
         self.assertIsInstance(context.exception, RateLimitError)
         self.assertEqual(context.exception.reset_at, -1)
+        self.assertIsNotNone(context.exception.headers)
+        self.assertEqual(context.exception.headers, {})
 
         self.assertEqual(rc._metrics["retries"], 1)