lago-python-client 1.45.0__tar.gz → 1.46.0__tar.gz

{lago_python_client-1.45.0 → lago_python_client-1.46.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lago-python-client
-Version: 1.45.0
+Version: 1.46.0
 Summary: Lago Python API Client
 Home-page: https://github.com/getlago/lago-python-client
 Author: Lovro Colic

{lago_python_client-1.45.0 → lago_python_client-1.46.0}/lago_python_client/base_client.py

@@ -1,16 +1,24 @@
 from abc import ABC, abstractmethod
-from typing import Type
+from typing import Optional, Type
 
 from lago_python_client.base_model import BaseModel
+from lago_python_client.services.rate_limit import RateLimitRetryConfig
 
 
 class BaseClient(ABC):
     """The base class used for each collection client."""
 
-    def __init__(self, base_url: str, api_key: str, base_ingest_url: str = ""):
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        base_ingest_url: str = "",
+        rate_limit_retry_config: Optional[RateLimitRetryConfig] = None,
+    ):
         self.base_url = base_url
         self.api_key = api_key
         self.base_ingest_url = base_ingest_url
+        self.rate_limit_retry_config = rate_limit_retry_config or RateLimitRetryConfig()
 
     @property
     @classmethod

{lago_python_client-1.45.0 → lago_python_client-1.46.0}/lago_python_client/client.py

@@ -32,6 +32,7 @@ from .payments.clients import PaymentClient
 from .plans.charges_client import PlanChargesClient
 from .plans.clients import PlanClient
 from .plans.fixed_charges_client import PlanFixedChargesClient
+from .services.rate_limit import RateLimitRetryConfig
 from .subscriptions.charges_client import SubscriptionChargesClient
 from .subscriptions.clients import SubscriptionClient
 from .subscriptions.fixed_charges_client import SubscriptionFixedChargesClient
@@ -53,12 +54,22 @@ class Client:
     API_PATH: Final[str] = "api/v1/"
 
     def __init__(
-        self, api_key: str = "", api_url: str = "", use_ingest_service: bool = False, ingest_api_url: str = ""
+        self,
+        api_key: str = "",
+        api_url: str = "",
+        use_ingest_service: bool = False,
+        ingest_api_url: str = "",
+        max_retries: int = 3,
+        retry_on_rate_limit: bool = True,
     ) -> None:
         self.api_key: str = api_key
         self.api_url: str = api_url
         self.use_ingest_service: bool = use_ingest_service
         self.ingest_api_url: str = ingest_api_url
+        self.rate_limit_retry_config: RateLimitRetryConfig = RateLimitRetryConfig(
+            max_retries=max_retries,
+            retry_on_rate_limit=retry_on_rate_limit,
+        )
 
     @property
     def base_api_url(self) -> str:
@@ -76,166 +87,172 @@ class Client:
 
         return urljoin(ingest_url, Client.API_PATH)
 
+    def _create_client(self, client_class, base_url, api_key, base_ingest_url=""):
+        """Create a client instance with rate limit config."""
+        if base_ingest_url:
+            return client_class(base_url, api_key, base_ingest_url, self.rate_limit_retry_config)
+        return client_class(base_url, api_key, rate_limit_retry_config=self.rate_limit_retry_config)
+
     @callable_cached_property
     def add_ons(self) -> AddOnClient:
-        return AddOnClient(self.base_api_url, self.api_key)
+        return self._create_client(AddOnClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def billable_metrics(self) -> BillableMetricClient:
-        return BillableMetricClient(self.base_api_url, self.api_key)
+        return self._create_client(BillableMetricClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def billing_entities(self) -> BillingEntityClient:
-        return BillingEntityClient(self.base_api_url, self.api_key)
+        return self._create_client(BillingEntityClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def coupons(self) -> CouponClient:
-        return CouponClient(self.base_api_url, self.api_key)
+        return self._create_client(CouponClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def applied_coupons(self) -> AppliedCouponClient:
-        return AppliedCouponClient(self.base_api_url, self.api_key)
+        return self._create_client(AppliedCouponClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def credit_notes(self) -> CreditNoteClient:
-        return CreditNoteClient(self.base_api_url, self.api_key)
+        return self._create_client(CreditNoteClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def customers(self) -> CustomerClient:
-        return CustomerClient(self.base_api_url, self.api_key)
+        return self._create_client(CustomerClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def customer_applied_coupons(self) -> CustomerAppliedCouponsClient:
-        return CustomerAppliedCouponsClient(self.base_api_url, self.api_key)
+        return self._create_client(CustomerAppliedCouponsClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def customer_credit_notes(self) -> CustomerCreditNotesClient:
-        return CustomerCreditNotesClient(self.base_api_url, self.api_key)
+        return self._create_client(CustomerCreditNotesClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def customer_invoices(self) -> CustomerInvoicesClient:
-        return CustomerInvoicesClient(self.base_api_url, self.api_key)
+        return self._create_client(CustomerInvoicesClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def customer_payment_methods(self) -> CustomerPaymentMethodsClient:
-        return CustomerPaymentMethodsClient(self.base_api_url, self.api_key)
+        return self._create_client(CustomerPaymentMethodsClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def customer_payments(self) -> CustomerPaymentsClient:
-        return CustomerPaymentsClient(self.base_api_url, self.api_key)
+        return self._create_client(CustomerPaymentsClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def customer_payment_requests(self) -> CustomerPaymentRequestsClient:
-        return CustomerPaymentRequestsClient(self.base_api_url, self.api_key)
+        return self._create_client(CustomerPaymentRequestsClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def customer_subscriptions(self) -> CustomerSubscriptionsClient:
-        return CustomerSubscriptionsClient(self.base_api_url, self.api_key)
+        return self._create_client(CustomerSubscriptionsClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def customer_wallets(self) -> CustomerWalletsClient:
-        return CustomerWalletsClient(self.base_api_url, self.api_key)
+        return self._create_client(CustomerWalletsClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def events(self) -> EventClient:
-        return EventClient(self.base_api_url, self.api_key, self.base_ingest_api_url)
+        return self._create_client(EventClient, self.base_api_url, self.api_key, self.base_ingest_api_url)
 
     @callable_cached_property
     def fees(self) -> FeeClient:
-        return FeeClient(self.base_api_url, self.api_key)
+        return self._create_client(FeeClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def gross_revenues(self) -> GrossRevenueClient:
-        return GrossRevenueClient(self.base_api_url, self.api_key)
+        return self._create_client(GrossRevenueClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def invoices(self) -> InvoiceClient:
-        return InvoiceClient(self.base_api_url, self.api_key)
+        return self._create_client(InvoiceClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def invoiced_usages(self) -> InvoicedUsageClient:
-        return InvoicedUsageClient(self.base_api_url, self.api_key)
+        return self._create_client(InvoicedUsageClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def mrrs(self) -> MrrClient:
-        return MrrClient(self.base_api_url, self.api_key)
+        return self._create_client(MrrClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def organizations(self) -> OrganizationClient:
-        return OrganizationClient(self.base_api_url, self.api_key)
+        return self._create_client(OrganizationClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def overdue_balances(self) -> OverdueBalanceClient:
-        return OverdueBalanceClient(self.base_api_url, self.api_key)
+        return self._create_client(OverdueBalanceClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def payment_receipts(self) -> PaymentReceiptClient:
-        return PaymentReceiptClient(self.base_api_url, self.api_key)
+        return self._create_client(PaymentReceiptClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def payment_requests(self) -> PaymentRequestClient:
-        return PaymentRequestClient(self.base_api_url, self.api_key)
+        return self._create_client(PaymentRequestClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def payments(self) -> PaymentClient:
-        return PaymentClient(self.base_api_url, self.api_key)
+        return self._create_client(PaymentClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def invoice_collections(self) -> InvoiceCollectionClient:
-        return InvoiceCollectionClient(self.base_api_url, self.api_key)
+        return self._create_client(InvoiceCollectionClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def plans(self) -> PlanClient:
-        return PlanClient(self.base_api_url, self.api_key)
+        return self._create_client(PlanClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def plan_charges(self) -> PlanChargesClient:
-        return PlanChargesClient(self.base_api_url, self.api_key)
+        return self._create_client(PlanChargesClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def plan_fixed_charges(self) -> PlanFixedChargesClient:
-        return PlanFixedChargesClient(self.base_api_url, self.api_key)
+        return self._create_client(PlanFixedChargesClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def subscriptions(self) -> SubscriptionClient:
-        return SubscriptionClient(self.base_api_url, self.api_key)
+        return self._create_client(SubscriptionClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def subscription_charges(self) -> SubscriptionChargesClient:
-        return SubscriptionChargesClient(self.base_api_url, self.api_key)
+        return self._create_client(SubscriptionChargesClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def subscription_fixed_charges(self) -> SubscriptionFixedChargesClient:
-        return SubscriptionFixedChargesClient(self.base_api_url, self.api_key)
+        return self._create_client(SubscriptionFixedChargesClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def taxes(self) -> TaxClient:
-        return TaxClient(self.base_api_url, self.api_key)
+        return self._create_client(TaxClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def usages(self) -> UsageClient:
-        return UsageClient(self.base_api_url, self.api_key)
+        return self._create_client(UsageClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def wallets(self) -> WalletClient:
-        return WalletClient(self.base_api_url, self.api_key)
+        return self._create_client(WalletClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def wallet_transactions(self) -> WalletTransactionClient:
-        return WalletTransactionClient(self.base_api_url, self.api_key)
+        return self._create_client(WalletTransactionClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def webhooks(self) -> WebhookClient:
-        return WebhookClient(self.base_api_url, self.api_key)
+        return self._create_client(WebhookClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def webhook_endpoints(self) -> WebhookEndpointClient:
-        return WebhookEndpointClient(self.base_api_url, self.api_key)
+        return self._create_client(WebhookEndpointClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def activity_logs(self) -> ActivityLogClient:
-        return ActivityLogClient(self.base_api_url, self.api_key)
+        return self._create_client(ActivityLogClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def api_logs(self) -> ApiLogClient:
-        return ApiLogClient(self.base_api_url, self.api_key)
+        return self._create_client(ApiLogClient, self.base_api_url, self.api_key)

lago_python_client-1.46.0/lago_python_client/exceptions.py

@@ -0,0 +1,69 @@
+from collections.abc import MutableMapping
+from http import HTTPStatus
+from typing import Any, Optional
+
+
+class LagoApiError(Exception):
+    def __init__(
+        self,
+        status_code: int,
+        url: Optional[str],
+        response: Any,
+        detail: Optional[str] = None,
+        headers: Optional[MutableMapping[str, str]] = None,
+    ) -> None:
+        if detail is None:
+            detail = HTTPStatus(status_code).phrase
+        self.status_code = status_code
+        self.url = url
+        self.response = response
+        self.detail = detail
+        self.headers = headers
+        super().__init__(self.response)
+
+    def __repr__(self) -> str:
+        class_name = self.__class__.__name__
+        return f"{class_name}(response={self.response!r}"
+
+
+class LagoRateLimitError(LagoApiError):
+    """Exception raised when rate limit is exceeded (HTTP 429)."""
+
+    def __init__(
+        self,
+        status_code: int,
+        url: Optional[str],
+        response: Any,
+        detail: Optional[str] = None,
+        headers: Optional[MutableMapping[str, str]] = None,
+    ) -> None:
+        super().__init__(
+            status_code=status_code,
+            url=url,
+            response=response,
+            detail=detail,
+            headers=headers,
+        )
+        # Parse rate limit headers
+        self.limit: Optional[int] = None
+        self.remaining: Optional[int] = None
+        self.reset: Optional[int] = None
+
+        if headers:
+            try:
+                self.limit = int(headers["x-ratelimit-limit"])
+            except (KeyError, ValueError, TypeError):
+                pass
+            try:
+                self.remaining = int(headers["x-ratelimit-remaining"])
+            except (KeyError, ValueError, TypeError):
+                pass
+            try:
+                self.reset = int(headers["x-ratelimit-reset"])
+            except (KeyError, ValueError, TypeError):
+                pass
+
+    def __repr__(self) -> str:
+        return (
+            f"LagoRateLimitError(limit={self.limit}, remaining={self.remaining}, reset={self.reset}, url={self.url!r})"
+        )

{lago_python_client-1.45.0 → lago_python_client-1.46.0}/lago_python_client/mixins.py

@@ -10,6 +10,7 @@ except ImportError:  # Python 3.7
 from collections.abc import Mapping
 
 from lago_python_client.base_model import BaseModel
+from lago_python_client.services.rate_limit import RateLimitRetryConfig
 
 from .services.json import to_json
 from .services.request import (
@@ -47,6 +48,8 @@ class _ClientMixin(Protocol[_PM_co]):
     def api_key(self) -> str: ...
     @property
     def base_url(self) -> str: ...
+    @property
+    def rate_limit_retry_config(self) -> RateLimitRetryConfig: ...
 
 
 class CreateCommandMixin(Generic[_M]):
@@ -71,6 +74,7 @@ class CreateCommandMixin(Generic[_M]):
             ),
             headers=make_headers(api_key=self.api_key),
             timeout=timeout,
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         # Process response data
@@ -105,6 +109,7 @@ class DestroyCommandMixin(Generic[_M]):
             ),
             headers=make_headers(api_key=self.api_key),
             timeout=timeout,
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         # Process response data
@@ -134,6 +139,7 @@ class FindAllCommandMixin(Generic[_M]):
             ),
             headers=make_headers(api_key=self.api_key),
             timeout=timeout,
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         # Process response data
@@ -167,6 +173,7 @@ class FindAllChildrenCommandMixin(Generic[_M]):
                 ),
                 query_pairs=options,
             ),
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         return prepare_index_response(
@@ -200,6 +207,7 @@ class FindChildCommandMixin(Generic[_M]):
                 query_pairs=options,
             ),
             headers=make_headers(api_key=self.api_key),
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         return prepare_object_response(
@@ -232,6 +240,7 @@ class CreateChildCommandMixin(Generic[_M]):
             ),
             content=to_json({self.ROOT_NAME: input_object.dict(exclude_none=True)}),
             headers=make_headers(api_key=self.api_key),
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         return prepare_object_response(
@@ -266,6 +275,7 @@ class UpdateChildCommandMixin(Generic[_M]):
             ),
             content=to_json({self.ROOT_NAME: input_object.dict(exclude_none=True)}),
             headers=make_headers(api_key=self.api_key),
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         return prepare_object_response(
@@ -298,6 +308,7 @@ class DestroyChildCommandMixin(Generic[_M]):
                 query_pairs=options,
             ),
             headers=make_headers(api_key=self.api_key),
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         return prepare_object_response(
@@ -327,6 +338,7 @@ class FindCommandMixin(Generic[_M]):
             ),
             headers=make_headers(api_key=self.api_key),
             timeout=timeout,
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         # Process response data
@@ -359,6 +371,7 @@ class UpdateCommandMixin(Generic[_M]):
             ),
             headers=make_headers(api_key=self.api_key),
             timeout=timeout,
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         # Process response data
@@ -389,6 +402,7 @@ class NestedCreateCommandMixin(Generic[_M]):
             ),
             headers=make_headers(api_key=self.api_key),
             timeout=timeout,
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         # Process response data
@@ -426,6 +440,7 @@ class NestedUpdateCommandMixin(Generic[_M]):
             ),
             headers=make_headers(api_key=self.api_key),
             timeout=timeout,
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         # Process response data
@@ -454,6 +469,7 @@ class NestedDestroyCommandMixin(Generic[_M]):
             ),
             headers=make_headers(api_key=self.api_key),
             timeout=timeout,
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         # Process response data
@@ -482,6 +498,7 @@ class NestedFindCommandMixin(Generic[_M]):
             ),
             headers=make_headers(api_key=self.api_key),
             timeout=timeout,
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         # Process response data
@@ -510,6 +527,7 @@ class NestedFindAllCommandMixin(Generic[_M]):
             ),
             headers=make_headers(api_key=self.api_key),
             timeout=timeout,
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         # Process response data

{lago_python_client-1.45.0 → lago_python_client-1.46.0}/lago_python_client/models/fee.py

@@ -53,6 +53,8 @@ class FeeResponse(BaseResponseModel):
     total_amount_cents: Optional[int]
     unit_amount_cents: Optional[int]  # deprecated
     precise_unit_amount: Optional[str]
+    sub_total_excluding_taxes_amount_cents: Optional[int]
+    sub_total_excluding_taxes_precise_amount_cents: Optional[str]
     precise_amount: Optional[str]
     precise_total_amount: Optional[str]
     taxes_precise_amount: Optional[str]

{lago_python_client-1.45.0 → lago_python_client-1.46.0}/lago_python_client/models/invoice_custom_section.py

@@ -10,16 +10,6 @@ class InvoiceCustomSectionInput(BaseModel):
     invoice_custom_section_codes: Optional[List[str]]
 
 
-class AppliedInvoiceCustomSection(BaseResponseModel):
-    lago_id: Optional[str]
-    invoice_custom_section_id: Optional[str]
-    created_at: Optional[str]
-
-
-class AppliedInvoiceCustomSections(BaseResponseModel):
-    __root__: List[AppliedInvoiceCustomSection]
-
-
 class InvoiceCustomSectionResponse(BaseResponseModel):
     lago_id: Optional[str]
     code: Optional[str]
@@ -30,5 +20,16 @@ class InvoiceCustomSectionResponse(BaseResponseModel):
     applied_to_organization: Optional[bool]  # Deprecated
 
 
+class AppliedInvoiceCustomSection(BaseResponseModel):
+    lago_id: Optional[str]
+    invoice_custom_section_id: Optional[str]
+    created_at: Optional[str]
+    invoice_custom_section: Optional[InvoiceCustomSectionResponse]
+
+
+class AppliedInvoiceCustomSections(BaseResponseModel):
+    __root__: List[AppliedInvoiceCustomSection]
+
+
 class InvoiceCustomSectionsResponseList(BaseResponseModel):
     __root__: List[InvoiceCustomSectionResponse]

lago_python_client-1.46.0/lago_python_client/services/rate_limit.py

@@ -0,0 +1,126 @@
+import time
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from httpx import Response
+
+from ..exceptions import LagoRateLimitError
+
+
+class RateLimitRetryConfig:
+    """Configuration for rate limit retry behavior."""
+
+    def __init__(
+        self,
+        max_retries: int = 3,
+        retry_on_rate_limit: bool = True,
+        base_backoff_seconds: float = 1.0,
+        backoff_multiplier: float = 2.0,
+        max_retry_delay: float = 20.0,
+    ):
+        """
+        Initialize rate limit retry configuration.
+
+        Args:
+            max_retries: Maximum number of retry attempts (0 means no retries).
+            retry_on_rate_limit: Whether to automatically retry on 429 responses.
+            base_backoff_seconds: Initial backoff duration in seconds for exponential backoff.
+            backoff_multiplier: Multiplier for exponential backoff between retries.
+            max_retry_delay: Maximum delay in seconds before a retry (default: 20).
+        """
+        self.max_retries = max_retries
+        self.retry_on_rate_limit = retry_on_rate_limit
+        self.base_backoff_seconds = base_backoff_seconds
+        self.backoff_multiplier = backoff_multiplier
+        self.max_retry_delay = max_retry_delay
+
+    def calculate_backoff(self, retry_attempt: int) -> float:
+        """
+        Calculate backoff duration for exponential backoff strategy.
+
+        Args:
+            retry_attempt: Current retry attempt number (0-based).
+
+        Returns:
+            Duration in seconds to wait before retrying.
+        """
+        return self.base_backoff_seconds * (self.backoff_multiplier**retry_attempt)
+
+
+def handle_rate_limit_response(
+    response: "Response",
+    config: RateLimitRetryConfig,
+    retry_attempt: int,
+) -> float:
+    """
+    Determine if and how long to wait before retrying a rate-limited request.
+
+    Args:
+        response: The HTTP response object (should be 429).
+        config: Rate limit retry configuration.
+        retry_attempt: Current retry attempt number (0-based).
+
+    Returns:
+        Duration in seconds to wait before retrying, or raises LagoRateLimitError.
+
+    Raises:
+        LagoRateLimitError: If retry is not configured or max retries exceeded.
+    """
+    # Check if retries are enabled
+    if not config.retry_on_rate_limit:
+        raise LagoRateLimitError(
+            status_code=response.status_code,
+            url=str(response.request.url),
+            response=None,
+            headers=response.headers,
+        )
+
+    # Check if we've exceeded max retries
+    if retry_attempt >= config.max_retries:
+        raise LagoRateLimitError(
+            status_code=response.status_code,
+            url=str(response.request.url),
+            response=None,
+            headers=response.headers,
+        )
+
+    # Try to get reset time from header
+    reset_seconds: Optional[int] = None
+    if "x-ratelimit-reset" in response.headers:
+        try:
+            reset_seconds = int(response.headers["x-ratelimit-reset"])
+        except (ValueError, TypeError):
+            pass
+
+    # Use header value if available, otherwise use exponential backoff
+    if reset_seconds is not None:
+        delay = float(reset_seconds)
+    else:
+        delay = config.calculate_backoff(retry_attempt)
+
+    # Cap at max_retry_delay
+    return min(delay, config.max_retry_delay)
+
+
+def is_rate_limit_response(response: "Response") -> bool:
+    """
+    Check if a response indicates rate limit exceeded.
+
+    Args:
+        response: The HTTP response to check.
+
+    Returns:
+        True if response is a 429 Too Many Requests, False otherwise.
+    """
+    return response.status_code == 429
+
+
+def wait_for_retry(duration: float) -> None:
+    """
+    Sleep for the specified duration before retrying.
+
+    Args:
+        duration: Number of seconds to wait.
+    """
+    if duration > 0:
+        time.sleep(duration)