bitvavo-api-upgraded 4.3.1__py3-none-any.whl → 4.4.1__py3-none-any.whl

{bitvavo_api_upgraded-4.3.1.dist-info → bitvavo_api_upgraded-4.4.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: bitvavo-api-upgraded
-Version: 4.3.1
+Version: 4.4.1
 Summary: A unit-tested fork of the Bitvavo API
 Author: Bitvavo BV (original code), NostraDavid
 Author-email: NostraDavid <55331731+NostraDavid@users.noreply.github.com>

{bitvavo_api_upgraded-4.3.1.dist-info → bitvavo_api_upgraded-4.4.1.dist-info}/RECORD

@@ -9,14 +9,14 @@ bitvavo_client/__init__.py,sha256=YXTBdP6fBREV34VeTqS_gkjfzIoHv5uSYhbqSUEeAVU,20
 bitvavo_client/adapters/__init__.py,sha256=9YVjMhNiAN6K1x7N0UvAXMQwuhOFy4W6Edrba1hW8KI,64
 bitvavo_client/adapters/returns_adapter.py,sha256=3HSAPw6HB9GCS8AbKmeidURpZXnvMZqkvalOu6JhBv0,14195
 bitvavo_client/auth/__init__.py,sha256=bjWu5WCKNNnNoLcVU290tKBml9M5afmcxaU_KrkisSQ,39
-bitvavo_client/auth/rate_limit.py,sha256=wv1UI733CVo8y5tI89CaUvomNpXLjbjSUh5vr9vn0ls,4949
+bitvavo_client/auth/rate_limit.py,sha256=iEfrzEvYvLQfhMSCy6epJQjDXyLkhcNFvH_zidW9omc,10559
 bitvavo_client/auth/signing.py,sha256=DJrI1R1SLKjl276opj9hN4RrKIgsMhxsSEDA8b7T04I,1037
 bitvavo_client/core/__init__.py,sha256=WqjaU9Ut5JdZwn4tsR1vDdrSfMjEJred3im6fvWpalc,39
 bitvavo_client/core/errors.py,sha256=jWHHQKqkkhpHS9TeKlccl7wuyuRrq0H_PGZ0bl6sbW4,460
 bitvavo_client/core/model_preferences.py,sha256=uPXjAD3B4UaBwzmhSN7k59oG71RGmV05y6-FGDKM184,1134
 bitvavo_client/core/private_models.py,sha256=lttKQJQ6sVVwgFJ7WsnXim185KZUfjjuuQzsciPuEL8,33232
 bitvavo_client/core/public_models.py,sha256=st1m1yOxutPhVQteJoRS72mzlQNeL7ynYjG1hqYg27w,37492
-bitvavo_client/core/settings.py,sha256=jUu_8FQERkJneFHEOW6aHNeYX8DRRcBn_PXIkIipVtQ,2146
+bitvavo_client/core/settings.py,sha256=EVvjxiecb7ju57JqOk0LNG_wjMmndrudvvPYoWFErxo,2147
 bitvavo_client/core/types.py,sha256=wxqGlbBf6UFMMnRak4H8b7rNymQQuFqKFR8mkSsRig8,429
 bitvavo_client/core/validation_helpers.py,sha256=2KeviuRXFiq4pgttHjC9q8gcrYmtLosSUrlvgnygMQY,3346
 bitvavo_client/df/__init__.py,sha256=1ui3dsRhDvy0NOoOi4zj5gR48u828Au9K_qtH9S1hIo,44
@@ -26,14 +26,14 @@ bitvavo_client/endpoints/base.py,sha256=gZwUHG1XapoVvE9F7yqU8NLt2-QETwUsGSwcHkwO
 bitvavo_client/endpoints/common.py,sha256=fc4gNNZ2zGMJJwkbHexNz6qMDLjl6dalQFGDXWmBo2E,2413
 bitvavo_client/endpoints/private.py,sha256=yChMe-HL2wFm6GBYoghURjdLzSxCPTYlEIOjysCrn3E,34589
 bitvavo_client/endpoints/public.py,sha256=EY7y3vuuo3li1BiPCM2KfSNnoa91X426DPtp8BvHiS8,21944
-bitvavo_client/facade.py,sha256=KZ8_yw9Ygtb8hK4_VIIwlrXGXIp43OJ4c-XncoYoaxE,1969
+bitvavo_client/facade.py,sha256=nVAhmAtO53FfE_lODIjV3IjnMvkU3xGHuxUH5t-CLJk,1994
 bitvavo_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 bitvavo_client/schemas/__init__.py,sha256=udqMyAFElrcBbNJIhoarQuTI-CF425JvPFqgLVjILU8,1126
 bitvavo_client/schemas/private_schemas.py,sha256=cG-cV5HKO8ZvWp3hjUPBFMT6Th0UBumMViI8gAZTyik,6143
 bitvavo_client/schemas/public_schemas.py,sha256=zfV6C_PQvNLLYEWS72ZD77Nm3XtRrEghKRhaFpgWHnI,4746
 bitvavo_client/transport/__init__.py,sha256=H7txnyuz6v84_GzdBiqpsehVQitEymgUTA5AJPeUEvg,44
-bitvavo_client/transport/http.py,sha256=hGablbfalBKAaJW9oQvz69oXpietBk7oGtCDZp1sQdc,9113
+bitvavo_client/transport/http.py,sha256=4ch-_fC6UATzQAUfh4VAQJwjcnuNnPmFGaV7swotkkc,13741
 bitvavo_client/ws/__init__.py,sha256=Q4SVEq3EihXLVUKpguMdxrhfNAoU8cncpMFbU6kIX_0,44
-bitvavo_api_upgraded-4.3.1.dist-info/WHEEL,sha256=F3mArEuDT3LDFEqo9fCiUx6ISLN64aIhcGSiIwtu4r8,79
-bitvavo_api_upgraded-4.3.1.dist-info/METADATA,sha256=TRpZGN-Wim27RSrTubvBcirUDBd0WvfB31ehdn1Yirw,35640
-bitvavo_api_upgraded-4.3.1.dist-info/RECORD,,
+bitvavo_api_upgraded-4.4.1.dist-info/WHEEL,sha256=Pi5uDq5Fdo_Rr-HD5h9BiPn9Et29Y9Sh8NhcJNnFU1c,79
+bitvavo_api_upgraded-4.4.1.dist-info/METADATA,sha256=GStFfK9ebWo5CEuTrc4N139mM8iWnfKfwo-wGGOsLFE,35640
+bitvavo_api_upgraded-4.4.1.dist-info/RECORD,,

{bitvavo_api_upgraded-4.3.1.dist-info → bitvavo_api_upgraded-4.4.1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.8.16
+Generator: uv 0.8.17
 Root-Is-Purelib: true
 Tag: py3-none-any

bitvavo_client/auth/rate_limit.py

@@ -5,6 +5,10 @@ from __future__ import annotations
 import time
 from typing import Protocol
 
+from structlog.stdlib import get_logger
+
+logger = get_logger()
+
 
 class RateLimitStrategy(Protocol):
     """Protocol for custom rate limit handling strategies."""
@@ -20,10 +24,9 @@ class DefaultRateLimitStrategy(RateLimitStrategy):
 
 
 class RateLimitManager:
-    """Manages rate limiting for multiple API keys and keyless requests.
+    """Manages rate limiting for multiple API keys.
 
-    Each API key index has its own rate limit state. Index -1 is reserved
-    for keyless requests.
+    Each API key index has its own rate limit state.
     """
 
     def __init__(self, default_remaining: int, buffer: int, strategy: RateLimitStrategy | None = None) -> None:
@@ -35,28 +38,51 @@ class RateLimitManager:
             strategy: Optional strategy callback when rate limit exceeded
         """
         self.default_remaining: int = default_remaining
-        self.state: dict[int, dict[str, int]] = {-1: {"remaining": default_remaining, "resetAt": 0}}
+        self.state: dict[int, dict[str, int]] = {}
         self.buffer: int = buffer
 
         self._strategy: RateLimitStrategy = strategy or DefaultRateLimitStrategy()
 
+        logger.info(
+            "rate-limit-manager-initialized",
+            default_remaining=default_remaining,
+            buffer=buffer,
+            strategy=type(self._strategy).__name__,
+        )
+
     def ensure_key(self, idx: int) -> None:
         """Ensure a key index exists in the state."""
         if idx not in self.state:
-            self.state[idx] = {"remaining": self.state[-1]["remaining"], "resetAt": 0}
+            self.state[idx] = {"remaining": self.default_remaining, "resetAt": 0}
+            logger.debug(
+                "rate-limit-key-initialized",
+                key_idx=idx,
+                default_remaining=self.default_remaining,
+            )
 
     def has_budget(self, idx: int, weight: int) -> bool:
         """Check if there's enough rate limit budget for a request.
 
         Args:
-            idx: API key index (-1 for keyless)
+            idx: API key index
             weight: Weight of the request
 
         Returns:
             True if request can be made within rate limits
         """
         self.ensure_key(idx)
-        return (self.state[idx]["remaining"] - weight) >= self.buffer
+        has_budget = (self.state[idx]["remaining"] - weight) >= self.buffer
+
+        logger.debug(
+            "rate-limit-budget-check",
+            key_idx=idx,
+            weight=weight,
+            remaining=self.state[idx]["remaining"],
+            buffer=self.buffer,
+            has_budget=has_budget,
+        )
+
+        return has_budget
 
     def record_call(self, idx: int, weight: int) -> None:
         """Record a request by decreasing the remaining budget.
@@ -66,12 +92,21 @@ class RateLimitManager:
         the response doesn't include rate limit headers.
 
         Args:
-            idx: API key index (-1 for keyless)
+            idx: API key index
             weight: Weight of the request
         """
         self.ensure_key(idx)
+        old_remaining = self.state[idx]["remaining"]
         self.state[idx]["remaining"] = max(0, self.state[idx]["remaining"] - weight)
 
+        logger.debug(
+            "rate-limit-call-recorded",
+            key_idx=idx,
+            weight=weight,
+            old_remaining=old_remaining,
+            new_remaining=self.state[idx]["remaining"],
+        )
+
     def update_from_headers(self, idx: int, headers: dict[str, str]) -> None:
         """Update rate limit state from response headers.
 
@@ -84,11 +119,24 @@ class RateLimitManager:
         remaining = headers.get("bitvavo-ratelimit-remaining")
         reset_at = headers.get("bitvavo-ratelimit-resetat")
 
+        old_state = dict(self.state[idx])
+
         if remaining is not None:
             self.state[idx]["remaining"] = int(remaining)
         if reset_at is not None:
             self.state[idx]["resetAt"] = int(reset_at)
 
+        logger.debug(
+            "rate-limit-updated-from-headers",
+            key_idx=idx,
+            old_remaining=old_state["remaining"],
+            new_remaining=self.state[idx]["remaining"],
+            old_reset_at=old_state["resetAt"],
+            new_reset_at=self.state[idx]["resetAt"],
+            has_remaining_header=remaining is not None,
+            has_reset_header=reset_at is not None,
+        )
+
     def update_from_error(self, idx: int, _err: dict[str, object]) -> None:
         """Update rate limit state from API error response.
 
@@ -97,30 +145,73 @@ class RateLimitManager:
             _err: Error response from API (unused but kept for interface compatibility)
         """
         self.ensure_key(idx)
+        old_remaining = self.state[idx]["remaining"]
+        old_reset_at = self.state[idx]["resetAt"]
+
         self.state[idx]["remaining"] = 0
         self.state[idx]["resetAt"] = int(time.time() * 1000) + 60_000
 
+        logger.warning(
+            "rate-limit-updated-from-error",
+            key_idx=idx,
+            old_remaining=old_remaining,
+            old_reset_at=old_reset_at,
+            new_reset_at=self.state[idx]["resetAt"],
+        )
+
     def sleep_until_reset(self, idx: int) -> None:
         """Sleep until rate limit resets for given key index.
 
         Args:
             idx: API key index
         """
+
         self.ensure_key(idx)
         now = int(time.time() * 1000)
         ms_left = max(0, self.state[idx]["resetAt"] - now)
-        time.sleep(ms_left / 1000 + 1)
+        sleep_seconds = ms_left / 1000 + 1
+
+        logger.info(
+            "rate-limit-exceeded",
+            key_idx=idx,
+            sleep_seconds=sleep_seconds,
+            reset_at=self.state[idx]["resetAt"],
+        )
+        time.sleep(sleep_seconds)
+
+        logger.info(
+            "rate-limit-sleep-completed",
+            key_idx=idx,
+            slept_seconds=sleep_seconds,
+        )
 
     def handle_limit(self, idx: int, weight: int) -> None:
         """Invoke the configured strategy when rate limit is exceeded."""
+        logger.info(
+            "rate-limit-handling-strategy",
+            key_idx=idx,
+            weight=weight,
+            strategy=type(self._strategy).__name__,
+        )
         self._strategy(self, idx, weight)
 
     def reset_key(self, idx: int) -> None:
         """Reset the remaining budget and reset time for a key index."""
         self.ensure_key(idx)
+        old_remaining = self.state[idx]["remaining"]
+        old_reset_at = self.state[idx]["resetAt"]
+
         self.state[idx]["remaining"] = self.default_remaining
         self.state[idx]["resetAt"] = 0
 
+        logger.info(
+            "rate-limit-key-reset",
+            key_idx=idx,
+            old_remaining=old_remaining,
+            old_reset_at=old_reset_at,
+            new_remaining=self.default_remaining,
+        )
+
     def get_remaining(self, idx: int) -> int:
         """Get remaining rate limit for key index.
 
@@ -144,3 +235,90 @@ class RateLimitManager:
         """
         self.ensure_key(idx)
         return self.state[idx]["resetAt"]
+
+    def find_best_available_key(self, available_keys: list[int], weight: int) -> int | None:
+        """Find the best API key for a request with given weight.
+
+        Prioritizes keys by:
+        1. Keys with sufficient budget (remaining - weight >= buffer)
+        2. Keys with the most remaining budget
+        3. Keys with the earliest reset time (if all are rate limited)
+
+        Args:
+            available_keys: List of available key indices
+            weight: Weight of the request
+
+        Returns:
+            Best key index or None if no keys are suitable
+        """
+        if not available_keys:
+            logger.debug("rate-limit-no-keys-available", weight=weight)
+            return None
+
+        suitable_keys = []
+        fallback_keys = []
+
+        for idx in available_keys:
+            self.ensure_key(idx)
+            if self.has_budget(idx, weight):
+                suitable_keys.append((idx, self.state[idx]["remaining"]))
+            else:
+                fallback_keys.append((idx, self.state[idx]["resetAt"]))
+
+        # Return key with most remaining budget if any have sufficient budget
+        if suitable_keys:
+            best_key = max(suitable_keys, key=lambda x: x[1])[0]
+            logger.debug(
+                "rate-limit-best-key-found",
+                key_idx=best_key,
+                weight=weight,
+                remaining=self.state[best_key]["remaining"],
+                suitable_keys_count=len(suitable_keys),
+            )
+            return best_key
+
+        # If no keys have budget, return the one that resets earliest
+        if fallback_keys:
+            fallback_key = min(fallback_keys, key=lambda x: x[1])[0]
+            logger.warning(
+                "rate-limit-using-fallback-key",
+                key_idx=fallback_key,
+                weight=weight,
+                reset_at=self.state[fallback_key]["resetAt"],
+                fallback_keys_count=len(fallback_keys),
+            )
+            return fallback_key
+
+        logger.warning("rate-limit-no-suitable-keys", weight=weight, available_keys=available_keys)
+        return None
+
+    def get_earliest_reset_time(self, key_indices: list[int]) -> int:
+        """Get the earliest reset time among the given keys.
+
+        Args:
+            key_indices: List of key indices to check
+
+        Returns:
+            Earliest reset timestamp in milliseconds, or 0 if no keys have reset times
+        """
+        if not key_indices:
+            logger.debug("rate-limit-no-keys-for-reset-time")
+            return 0
+
+        reset_times = []
+        for idx in key_indices:
+            self.ensure_key(idx)
+            reset_at = self.state[idx]["resetAt"]
+            if reset_at > 0:  # Only consider keys that actually have a reset time
+                reset_times.append(reset_at)
+
+        earliest_reset = min(reset_times) if reset_times else 0
+
+        logger.debug(
+            "rate-limit-earliest-reset-time",
+            key_indices=key_indices,
+            keys_with_reset=len(reset_times),
+            earliest_reset=earliest_reset,
+        )
+
+        return earliest_reset

bitvavo_client/core/settings.py

@@ -30,7 +30,7 @@ class BitvavoSettings(BaseSettings):
 
     # Client behavior
     default_rate_limit: int = Field(default=1_000, description="Default rate limit for new API keys")
-    rate_limit_buffer: int = Field(default=0, description="Rate limit buffer to avoid hitting limits")
+    rate_limit_buffer: int = Field(default=50, description="Rate limit buffer to avoid hitting limits")
     lag_ms: int = Field(default=0, description="Artificial lag to add to requests in milliseconds")
     debugging: bool = Field(default=False, description="Enable debug logging")
 

bitvavo_client/facade.py

@@ -38,8 +38,8 @@ class BitvavoClient:
         """
         self.settings = settings or BitvavoSettings()
         self.rate_limiter = RateLimitManager(
-            self.settings.default_rate_limit,
-            self.settings.rate_limit_buffer,
+            default_remaining=self.settings.default_rate_limit,
+            buffer=self.settings.rate_limit_buffer,
         )
         self.http = HTTPClient(self.settings, self.rate_limiter)
 

bitvavo_client/transport/http.py

@@ -7,6 +7,7 @@ from typing import TYPE_CHECKING, Any
 
 import httpx
 from returns.result import Failure, Result
+from structlog.stdlib import get_logger
 
 from bitvavo_client.adapters.returns_adapter import (
     BitvavoError,
@@ -19,6 +20,8 @@ if TYPE_CHECKING:  # pragma: no cover
     from bitvavo_client.core.settings import BitvavoSettings
     from bitvavo_client.core.types import AnyDict
 
+logger = get_logger(__name__)
+
 
 class HTTPClient:
     """HTTP client for Bitvavo REST API with rate limiting and authentication."""
@@ -30,11 +33,13 @@ class HTTPClient:
             settings: Bitvavo settings configuration
             rate_limiter: Rate limit manager instance
         """
+
         self.settings: BitvavoSettings = settings
         self.rate_limiter: RateLimitManager = rate_limiter
         self._keys: list[tuple[str, str]] = [(item["key"], item["secret"]) for item in self.settings.api_keys]
         if not self._keys:
             msg = "API keys are required"
+            logger.error("api-keys-required")
             raise ValueError(msg)
 
         for idx in range(len(self._keys)):
@@ -47,6 +52,7 @@ class HTTPClient:
 
         key, secret = self._keys[0]
         self.configure_key(key, secret, 0)
+        logger.info("http-client-initialized", key_count=len(self._keys))
 
     def configure_key(self, key: str, secret: str, index: int) -> None:
         """Configure API key for authenticated requests.
@@ -59,18 +65,23 @@ class HTTPClient:
         self.api_key = key
         self.api_secret = secret
         self.key_index = index
+        key_suffix = key[-4:] if len(key) >= 4 else "short"
+        logger.debug("api-key-configured", index=index, key_suffix=key_suffix)
 
     def select_key(self, index: int) -> None:
         """Select a specific API key by index."""
         if not (0 <= index < len(self._keys)):
             msg = "API key index out of range"
+            logger.error("api-key-index-out-of-range", index=index, available_keys=len(self._keys))
             raise IndexError(msg)
         key, secret = self._keys[index]
         self.configure_key(key, secret, index)
+        logger.debug("api-key-selected", index=index)
 
     def _rotate_key(self) -> bool:
         """Rotate to the next configured API key if available."""
         if len(self._keys) <= 1:
+            logger.debug("key-rotation-skipped", reason="only-one-key")
             return False
 
         next_idx = (self.key_index + 1) % len(self._keys)
@@ -78,14 +89,65 @@ class HTTPClient:
         reset_at = self.rate_limiter.get_reset_at(next_idx)
 
         if now < reset_at:
+            logger.info("rotating-to-key-with-sleep", next_index=next_idx)
             self.rate_limiter.sleep_until_reset(next_idx)
             self.rate_limiter.reset_key(next_idx)
         elif self.rate_limiter.get_remaining(next_idx) <= self.rate_limiter.buffer:
+            logger.debug("rotating-to-key-with-reset", next_index=next_idx, reason="low-remaining-budget")
             self.rate_limiter.reset_key(next_idx)
 
         self.select_key(next_idx)
+        logger.info("key-rotated", from_index=self.key_index, to_index=next_idx)
         return True
 
+    def _find_available_key(self, weight: int) -> int | None:
+        """Find the best available API key for a request with given weight.
+
+        Args:
+            weight: Weight of the request
+
+        Returns:
+            Best key index or None if all keys are rate limited
+        """
+        available_keys = list(range(len(self._keys)))
+        best_key = self.rate_limiter.find_best_available_key(available_keys, weight)
+        if best_key is not None:
+            logger.debug("available-key-found", key_index=best_key, weight=weight)
+        else:
+            logger.warning("no-available-keys", weight=weight)
+        return best_key
+
+    def _handle_rate_limit_exhaustion(self, weight: int) -> None:
+        """Handle situation when all API keys are rate limited.
+
+        Sleeps until the earliest key reset time and then resets that key.
+
+        Args:
+            weight: Weight of the original request
+        """
+        logger.warning("all-keys-rate-limited", weight=weight)
+        all_keys = list(range(len(self._keys)))
+        earliest_reset = self.rate_limiter.get_earliest_reset_time(all_keys)
+
+        if earliest_reset > 0:
+            # Find which key has the earliest reset time
+            now = int(time.time() * 1000)
+            for idx in all_keys:
+                if self.rate_limiter.get_reset_at(idx) == earliest_reset:
+                    if now < earliest_reset:
+                        # Sleep until this key resets
+                        sleep_ms = earliest_reset - now
+                        logger.info("sleeping-until-key-reset", key_index=idx, sleep_ms=sleep_ms)
+                        self.rate_limiter.sleep_until_reset(idx)
+                    self.rate_limiter.reset_key(idx)
+                    self.select_key(idx)
+                    logger.info("key-reset-after-exhaustion", key_index=idx)
+                    return
+
+        # Fallback to current key's rate limit strategy
+        logger.debug("fallback-to-current-key", key_index=self.key_index)
+        self.rate_limiter.handle_limit(self.key_index, weight)
+
     def request(
         self,
         method: str,
@@ -108,10 +170,20 @@ class HTTPClient:
         Raises:
             HTTPError: On transport-level failures
         """
+        logger.debug("making-request", method=method, endpoint=endpoint, weight=weight)
         idx = self.key_index
         self._ensure_rate_limit_initialized()
 
+        # Try to find the best available key for this request
+        best_key = self._find_available_key(weight)
+        if best_key is not None and best_key != idx:
+            logger.debug("switching-to-best-key", from_index=idx, to_index=best_key)
+            self.select_key(best_key)
+            idx = best_key
+
+        # If current key doesn't have budget, try rotation
         if not self.rate_limiter.has_budget(idx, weight):
+            logger.debug("key-lacks-budget", key_index=idx, weight=weight)
             for _ in range(len(self._keys)):
                 if self.rate_limiter.has_budget(idx, weight):
                     break
@@ -119,18 +191,25 @@ class HTTPClient:
                 idx = self.key_index
                 if not rotated:
                     break
+
+            # If still no budget after trying all keys, handle exhaustion smartly
             if not self.rate_limiter.has_budget(idx, weight):
-                self.rate_limiter.handle_limit(idx, weight)
+                logger.warning("no-budget-after-rotation", weight=weight)
+                self._handle_rate_limit_exhaustion(weight)
+                idx = self.key_index  # Update idx after potential key change
 
         url = f"{self.settings.rest_url}{endpoint}"
         headers = self._create_auth_headers(method, endpoint, body)
 
         # Update rate limit usage for this call
         self.rate_limiter.record_call(idx, weight)
+        logger.debug("weight-recorded", weight=weight, key_index=idx)
 
         try:
             response = self._make_http_request(method, url, headers, body)
+            logger.debug("request-completed", status_code=response.status_code)
         except httpx.HTTPError as exc:
+            logger.error("http-request-failed", error=str(exc))
             return Failure(exc)
 
         self._update_rate_limits(response, idx)
@@ -141,6 +220,7 @@ class HTTPClient:
         """Ensure the initial rate limit state is fetched from the API."""
         if self._rate_limit_initialized:
             return
+        logger.info("initializing-rate-limit-state")
         self._rate_limit_initialized = True
         self._initialize_rate_limit()
 
@@ -148,6 +228,7 @@ class HTTPClient:
         """Fetch initial rate limit and handle potential rate limit errors."""
         endpoint = "/account"
         url = f"{self.settings.rest_url}{endpoint}"
+        logger.debug("fetching-initial-rate-limit")
 
         while True:
             headers = self._create_auth_headers("GET", endpoint, None)
@@ -156,7 +237,8 @@ class HTTPClient:
 
             try:
                 response = self._make_http_request("GET", url, headers, None)
-            except httpx.HTTPError:
+            except httpx.HTTPError as exc:
+                logger.warning("rate-limit-init-failed", error=str(exc))
                 return
 
             self._update_rate_limits(response, self.key_index)
@@ -172,15 +254,19 @@ class HTTPClient:
                     if isinstance(err, dict):
                         err_code = str(err.get("code", ""))
             if response.status_code == httpx.codes.TOO_MANY_REQUESTS and err_code == "101":
+                logger.info("rate-limited-during-init", error_code=err_code)
                 self.rate_limiter.sleep_until_reset(self.key_index)
                 self.rate_limiter.reset_key(self.key_index)
                 continue
 
             if self.rate_limiter.get_remaining(self.key_index) < self.rate_limiter.buffer:
+                remaining = self.rate_limiter.get_remaining(self.key_index)
+                logger.info("low-budget-during-init", remaining=remaining)
                 self.rate_limiter.sleep_until_reset(self.key_index)
                 self.rate_limiter.reset_key(self.key_index)
                 continue
 
+            logger.info("rate-limit-initialization-completed")
             break
 
     def _create_auth_headers(self, method: str, endpoint: str, body: AnyDict | None) -> dict[str, str]:
@@ -216,6 +302,7 @@ class HTTPClient:
                 return httpx.delete(url, headers=headers, timeout=timeout)
             case _:
                 msg = f"Unsupported HTTP method: {method}"
+                logger.error("unsupported-http-method", method=method)
                 raise ValueError(msg)
 
     def _update_rate_limits(self, response: httpx.Response, idx: int) -> None:
@@ -227,10 +314,13 @@ class HTTPClient:
 
         if isinstance(json_data, dict) and "error" in json_data:
             if self._is_rate_limit_error(response, json_data):
+                logger.warning("rate-limit-error-detected", key_index=idx)
                 self.rate_limiter.update_from_error(idx, json_data)
             else:
+                logger.debug("non-rate-limit-error", key_index=idx)
                 self.rate_limiter.update_from_headers(idx, dict(response.headers))
         else:
+            logger.debug("successful-response", key_index=idx)
             self.rate_limiter.update_from_headers(idx, dict(response.headers))
 
     def _is_rate_limit_error(self, response: httpx.Response, json_data: dict[str, Any]) -> bool: