feat: Add retry_after property to ApiError

Author: davidgrayston-paddle

CHANGELOG.md

@@ -6,6 +6,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 Check our main [developer changelog](https://developer.paddle.com/?utm_source=dx&utm_medium=paddle-python-sdk) for information about changes to the Paddle Billing platform, the Paddle API, and other developer tools.
 
+## [Unreleased]
+
+### Added
+
+- `ApiError` will now have `retry_after` property set for [too_many_requests](https://developer.paddle.com/errors/shared/too_many_requests?utm_source=dx&utm_medium=paddle-python-sdk) errors
+
 ## 1.10.0 - 2025-08-15
 
 ### Added

paddle_billing/Exceptions/ApiError.py

@@ -1,16 +1,18 @@
 from paddle_billing.Exceptions.FieldError import FieldError
 
-from requests import HTTPError
+from requests import HTTPError, Response
 
 
 class ApiError(HTTPError):
-    def __init__(self, response, error_type, error_code, detail, docs_url, *field_errors):
+    def __init__(self, response: Response, error_type: str, error_code: str, detail: str, docs_url: str, *field_errors):
         super().__init__(detail, response=response)
         self.error_type = error_type
         self.error_code = error_code
         self.detail = detail
         self.docs_url = docs_url
         self.field_errors = field_errors
+        retry_after = response.headers.get("Retry-After")
+        self.retry_after = int(retry_after) if retry_after else None
 
     def __repr__(self):
         return (
@@ -19,6 +21,6 @@ def __repr__(self):
         )
 
     @classmethod
-    def from_error_data(cls, response, error):
+    def from_error_data(cls, response: Response, error):
         field_errors = [FieldError(fe["field"], fe["message"]) for fe in error.get("errors", [])]
         return cls(response, error["type"], error["code"], error["detail"], error["documentation_url"], *field_errors)

tests/Functional/Client/test_Client.py

@@ -19,6 +19,8 @@ class TestClient:
             "expected_reason",
             "expected_response_body",
             "expected_exception",
+            "headers",
+            "expected_retry_after",
         ],
         [
             (
@@ -35,6 +37,8 @@ class TestClient:
                     "meta": {"request_id": "f00bb3ca-399d-4686-889c-50b028f4c912"},
                 },
                 ApiError,
+                {},
+                None,
             ),
             (
                 404,
@@ -49,6 +53,8 @@ class TestClient:
                     "meta": {"request_id": "f00bb3ca-399d-4686-889c-50b028f4c912"},
                 },
                 ApiError,
+                {},
+                None,
             ),
             (
                 400,
@@ -63,12 +69,31 @@ class TestClient:
                     "meta": {"request_id": "f00bb3ca-399d-4686-889c-50b028f4c912"},
                 },
                 AddressApiError,
+                {},
+                None,
+            ),
+            (
+                429,
+                "Too Many Requests",
+                {
+                    "error": {
+                        "type": "request_error",
+                        "code": "too_many_requests",
+                        "detail": "IP address exceeded the allowed rate limit. Retry after the number of seconds in the Retry-After header.",
+                        "documentation_url": "https://developer.paddle.com/errors/shared/too_many_requests",
+                    },
+                    "meta": {"request_id": "f00bb3ca-399d-4686-889c-50b028f4c912"},
+                },
+                ApiError,
+                {"Retry-After": "42"},
+                42,
             ),
         ],
         ids=[
             "Returns bad_request response",
             "Returns not_found response",
             "Returns address_location_not_allowed response",
+            "Returns too_many_requests response",
         ],
     )
     def test_post_raw_returns_error_response(
@@ -80,6 +105,8 @@ def test_post_raw_returns_error_response(
         expected_reason,
         expected_response_body,
         expected_exception,
+        headers,
+        expected_retry_after,
     ):
         expected_request_url = f"{test_client.base_url}/some/url"
         expected_request_body = {"some_property": "some value"}
@@ -88,6 +115,7 @@ def test_post_raw_returns_error_response(
             status_code=expected_response_status,
             text=dumps(expected_response_body),
             reason=expected_reason,
+            headers=headers,
         )
 
         with raises(expected_exception) as exception_info:
@@ -111,6 +139,7 @@ def test_post_raw_returns_error_response(
         assert api_error.error_code == expected_response_body["error"]["code"]
         assert api_error.detail == expected_response_body["error"]["detail"]
         assert api_error.docs_url == expected_response_body["error"]["documentation_url"]
+        assert api_error.retry_after == expected_retry_after
 
         if "errors" in expected_response_body["error"]:
             assert len(api_error.field_errors) == len(expected_response_body["error"]["errors"])