keycycle 0.3.2__tar.gz → 0.5.0__tar.gz

{keycycle-0.3.2 → keycycle-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: keycycle
-Version: 0.3.2
+Version: 0.5.0
 Summary: A thread-safe key rotation and rate limiting manager for API keys.
 Author-email: William Jin <jinwilliam.jin@gmail.com>
 Classifier: Programming Language :: Python :: 3

{keycycle-0.3.2 → keycycle-0.5.0}/keycycle/adapters/generic_adapter.py

@@ -35,7 +35,7 @@ from ..config.constants import (
 from ..core.utils import (
     is_rate_limit_error,
     is_temporary_rate_limit_error,
-    is_payment_required_error,
+    is_dead_key_error,
     get_key_suffix,
 )
 from ..core.backoff import ExponentialBackoff, BackoffConfig
@@ -275,13 +275,20 @@ class BaseGenericRotatingClient(Generic[T]):
 
         return self.config.client_class(**final_kwargs)
 
-    def _record_usage(self, key_usage: KeyUsage, model_id: str, actual_tokens: int) -> None:
+    def _record_usage(
+        self,
+        key_usage: KeyUsage,
+        model_id: str,
+        actual_tokens: int,
+        track_usage: Optional[bool] = None,
+    ) -> None:
         """Record usage for a key."""
         self.manager.record_usage(
             key_obj=key_usage,
             model_id=model_id,
             actual_tokens=actual_tokens,
             estimated_tokens=self.config.estimated_tokens,
+            track_usage=track_usage,
         )
 
     def _extract_usage(self, response: Any) -> int:
@@ -301,13 +308,16 @@ class SyncGenericRotatingClient(BaseGenericRotatingClient[T]):
 
     def _execute(self, path: List[str], args: tuple, kwargs: dict) -> Any:
         """Execute a method call with key rotation."""
+        # Per-call tracking override - popped before the kwargs reach the real
+        # client, which may reject unknown keyword arguments.
+        track_usage = kwargs.pop("track_usage", None)
         model_id = self._get_model_id(kwargs)
         limits = self.limit_resolver(model_id, None)
 
         for attempt in range(self.config.max_retries + 1):
-            key_usage = self.manager.get_key(model_id, limits, self.config.estimated_tokens)
+            key_usage = self.manager.acquire_key(model_id, limits, self.config.estimated_tokens)
             if not key_usage:
-                raise RuntimeError(f"No available keys for {model_id}")
+                raise RuntimeError(self.manager.unavailable_message(model_id))
 
             # Create backoff for temporary rate limits
             temp_backoff = ExponentialBackoff(BackoffConfig(
@@ -331,9 +341,11 @@ class SyncGenericRotatingClient(BaseGenericRotatingClient[T]):
                     if hasattr(result, "__iter__") and not isinstance(result, (str, bytes, dict, list)):
                         # Check if it looks like a generator/iterator
                         if hasattr(result, "__next__") or inspect.isgenerator(result):
-                            return self._wrap_stream(result, key_usage, model_id)
+                            return self._wrap_stream(result, key_usage, model_id, track_usage)
 
-                    self._record_usage(key_usage, model_id, self._extract_usage(result))
+                    self._record_usage(
+                        key_usage, model_id, self._extract_usage(result), track_usage
+                    )
                     return result
 
                 except Exception as e:
@@ -348,11 +360,11 @@ class SyncGenericRotatingClient(BaseGenericRotatingClient[T]):
                         time.sleep(delay)
                         continue  # Retry with SAME key
 
-                    # Payment required (quota/credits exhausted) - key is dead
+                    # Dead key (401/403 revoked/denied, 402 credits exhausted) - key is dead
                     # for this process, rotate to next key
-                    if is_payment_required_error(e) and attempt < self.config.max_retries:
+                    if is_dead_key_error(e) and attempt < self.config.max_retries:
                         logger.warning(
-                            "402/PaymentRequired hit for %s on key ...%s. Marking key dead and rotating. (Attempt %d/%d)",
+                            "Dead key (401/402/403) hit for %s on key ...%s. Marking key dead and rotating. (Attempt %d/%d)",
                             model_id, get_key_suffix(key_usage.api_key),
                             attempt + 1, self.config.max_retries + 1
                         )
@@ -373,7 +385,7 @@ class SyncGenericRotatingClient(BaseGenericRotatingClient[T]):
                         time.sleep(KEY_ROTATION_DELAY_SECONDS)
                         break  # Break inner loop, continue outer loop with new key
 
-                    self._record_usage(key_usage, model_id, 0)
+                    self._record_usage(key_usage, model_id, 0, track_usage)
                     raise
             else:
                 # Inner loop exhausted without success - continue to next key
@@ -389,7 +401,11 @@ class SyncGenericRotatingClient(BaseGenericRotatingClient[T]):
         raise RuntimeError(f"All retry attempts exhausted for {model_id}")
 
     def _wrap_stream(
-        self, generator: Generator, key_usage: KeyUsage, model_id: str
+        self,
+        generator: Generator,
+        key_usage: KeyUsage,
+        model_id: str,
+        track_usage: Optional[bool] = None,
     ) -> Generator:
         """Wrap a streaming response to track usage and handle errors."""
         final_tokens = 0
@@ -401,9 +417,9 @@ class SyncGenericRotatingClient(BaseGenericRotatingClient[T]):
                     final_tokens = chunk_tokens
                 yield chunk
         except Exception as e:
-            if is_payment_required_error(e):
+            if is_dead_key_error(e):
                 logger.warning(
-                    "402/PaymentRequired hit during streaming for %s on key ...%s. Marking key dead.",
+                    "Dead key (401/402/403) hit during streaming for %s on key ...%s. Marking key dead.",
                     model_id, get_key_suffix(key_usage.api_key)
                 )
                 key_usage.mark_dead()
@@ -417,7 +433,7 @@ class SyncGenericRotatingClient(BaseGenericRotatingClient[T]):
                 self.manager.force_rotate_index()
             raise
         finally:
-            self._record_usage(key_usage, model_id, final_tokens)
+            self._record_usage(key_usage, model_id, final_tokens, track_usage)
 
 
 class SyncGenericProxyHelper:
@@ -442,13 +458,16 @@ class AsyncGenericRotatingClient(BaseGenericRotatingClient[T]):
 
     async def _execute(self, path: List[str], args: tuple, kwargs: dict) -> Any:
         """Execute a method call with key rotation (async)."""
+        # Per-call tracking override - popped before the kwargs reach the real
+        # client, which may reject unknown keyword arguments.
+        track_usage = kwargs.pop("track_usage", None)
         model_id = self._get_model_id(kwargs)
         limits = self.limit_resolver(model_id, None)
 
         for attempt in range(self.config.max_retries + 1):
-            key_usage = self.manager.get_key(model_id, limits, self.config.estimated_tokens)
+            key_usage = await self.manager.acquire_key_async(model_id, limits, self.config.estimated_tokens)
             if not key_usage:
-                raise RuntimeError(f"No available keys for {model_id}")
+                raise RuntimeError(self.manager.unavailable_message(model_id))
 
             # Create backoff for temporary rate limits
             temp_backoff = ExponentialBackoff(BackoffConfig(
@@ -470,9 +489,11 @@ class AsyncGenericRotatingClient(BaseGenericRotatingClient[T]):
 
                     # Handle async streaming responses
                     if hasattr(result, "__aiter__"):
-                        return self._wrap_stream(result, key_usage, model_id)
+                        return self._wrap_stream(result, key_usage, model_id, track_usage)
 
-                    self._record_usage(key_usage, model_id, self._extract_usage(result))
+                    self._record_usage(
+                        key_usage, model_id, self._extract_usage(result), track_usage
+                    )
                     return result
 
                 except Exception as e:
@@ -487,11 +508,11 @@ class AsyncGenericRotatingClient(BaseGenericRotatingClient[T]):
                         await asyncio.sleep(delay)
                         continue  # Retry with SAME key
 
-                    # Payment required (quota/credits exhausted) - key is dead
+                    # Dead key (401/403 revoked/denied, 402 credits exhausted) - key is dead
                     # for this process, rotate to next key
-                    if is_payment_required_error(e) and attempt < self.config.max_retries:
+                    if is_dead_key_error(e) and attempt < self.config.max_retries:
                         logger.warning(
-                            "402/PaymentRequired hit for %s on key ...%s. Marking key dead and rotating. (Attempt %d/%d)",
+                            "Dead key (401/402/403) hit for %s on key ...%s. Marking key dead and rotating. (Attempt %d/%d)",
                             model_id, get_key_suffix(key_usage.api_key),
                             attempt + 1, self.config.max_retries + 1
                         )
@@ -512,7 +533,7 @@ class AsyncGenericRotatingClient(BaseGenericRotatingClient[T]):
                         await asyncio.sleep(KEY_ROTATION_DELAY_SECONDS)
                         break  # Break inner loop, continue outer loop with new key
 
-                    self._record_usage(key_usage, model_id, 0)
+                    self._record_usage(key_usage, model_id, 0, track_usage)
                     raise
             else:
                 # Inner loop exhausted without success - continue to next key
@@ -528,7 +549,11 @@ class AsyncGenericRotatingClient(BaseGenericRotatingClient[T]):
         raise RuntimeError(f"All retry attempts exhausted for {model_id}")
 
     async def _wrap_stream(
-        self, generator: AsyncGenerator, key_usage: KeyUsage, model_id: str
+        self,
+        generator: AsyncGenerator,
+        key_usage: KeyUsage,
+        model_id: str,
+        track_usage: Optional[bool] = None,
     ) -> AsyncGenerator:
         """Wrap an async streaming response to track usage and handle errors."""
         final_tokens = 0
@@ -540,9 +565,9 @@ class AsyncGenericRotatingClient(BaseGenericRotatingClient[T]):
                     final_tokens = chunk_tokens
                 yield chunk
         except Exception as e:
-            if is_payment_required_error(e):
+            if is_dead_key_error(e):
                 logger.warning(
-                    "402/PaymentRequired hit during streaming for %s on key ...%s. Marking key dead.",
+                    "Dead key (401/402/403) hit during streaming for %s on key ...%s. Marking key dead.",
                     model_id, get_key_suffix(key_usage.api_key)
                 )
                 key_usage.mark_dead()
@@ -556,7 +581,7 @@ class AsyncGenericRotatingClient(BaseGenericRotatingClient[T]):
                 self.manager.force_rotate_index()
             raise
         finally:
-            self._record_usage(key_usage, model_id, final_tokens)
+            self._record_usage(key_usage, model_id, final_tokens, track_usage)
 
 
 class AsyncGenericProxyHelper:

{keycycle-0.3.2 → keycycle-0.5.0}/keycycle/adapters/openai_adapter.py

@@ -14,7 +14,7 @@ from ..config.constants import (
 from ..core.utils import (
     is_rate_limit_error,
     is_temporary_rate_limit_error,
-    is_payment_required_error,
+    is_dead_key_error,
     get_key_suffix,
 )
 from ..core.backoff import ExponentialBackoff, BackoffConfig
@@ -97,12 +97,19 @@ class BaseRotatingClient:
         if self.base_url:
             self.client_kwargs['base_url'] = self.base_url
 
-    def _record_usage(self, key_usage: KeyUsage, model_id: str, actual_tokens: int) -> None:
+    def _record_usage(
+        self,
+        key_usage: KeyUsage,
+        model_id: str,
+        actual_tokens: int,
+        track_usage: Optional[bool] = None,
+    ) -> None:
         self.manager.record_usage(
             key_obj=key_usage,
             model_id=model_id,
             actual_tokens=actual_tokens,
-            estimated_tokens=self.estimated_tokens
+            estimated_tokens=self.estimated_tokens,
+            track_usage=track_usage
         )
 
     def _extract_usage(self, response: Any) -> int:
@@ -123,6 +130,9 @@ class RotatingOpenAIClient(BaseRotatingClient):
         return SyncProxyHelper(self, [name])
 
     def _execute(self, path: List[str], args, kwargs):
+        # Per-call tracking override - popped before the kwargs reach the real
+        # OpenAI client, which rejects unknown keyword arguments.
+        track_usage = kwargs.pop('track_usage', None)
         model_id = kwargs.get('model', self.default_model)
         if 'model' not in kwargs:
             kwargs['model'] = model_id
@@ -132,9 +142,9 @@ class RotatingOpenAIClient(BaseRotatingClient):
             kwargs['stream_options'] = {"include_usage": True}
 
         for attempt in range(self.max_retries + 1):
-            key_usage = self.manager.get_key(model_id, limits, self.estimated_tokens)
+            key_usage = self.manager.acquire_key(model_id, limits, self.estimated_tokens)
             if not key_usage:
-                raise RuntimeError(f"No available keys for {model_id}")
+                raise RuntimeError(self.manager.unavailable_message(model_id))
 
             # Create backoff for temporary rate limits
             temp_backoff = ExponentialBackoff(BackoffConfig(
@@ -154,9 +164,11 @@ class RotatingOpenAIClient(BaseRotatingClient):
                     result = target(*args, **kwargs)
 
                     if kwargs.get('stream', False):
-                        return self._wrap_stream(result, key_usage, model_id)
+                        return self._wrap_stream(result, key_usage, model_id, track_usage)
 
-                    self._record_usage(key_usage, model_id, self._extract_usage(result))
+                    self._record_usage(
+                        key_usage, model_id, self._extract_usage(result), track_usage
+                    )
                     return result
 
                 except Exception as e:
@@ -171,11 +183,11 @@ class RotatingOpenAIClient(BaseRotatingClient):
                         time.sleep(delay)
                         continue  # Retry with SAME key
 
-                    # Payment required (quota/credits exhausted) - key is dead
+                    # Dead key (401/403 revoked/denied, 402 credits exhausted) - key is dead
                     # for this process, rotate to next key
-                    if is_payment_required_error(e) and attempt < self.max_retries:
+                    if is_dead_key_error(e) and attempt < self.max_retries:
                         logger.warning(
-                            "402/PaymentRequired hit for %s on key ...%s. Marking key dead and rotating. (Attempt %d/%d)",
+                            "Dead key (401/402/403) hit for %s on key ...%s. Marking key dead and rotating. (Attempt %d/%d)",
                             model_id, get_key_suffix(key_usage.api_key), attempt + 1, self.max_retries + 1
                         )
                         key_usage.mark_dead()
@@ -194,7 +206,7 @@ class RotatingOpenAIClient(BaseRotatingClient):
                         time.sleep(KEY_ROTATION_DELAY_SECONDS)
                         break  # Break inner loop, continue outer loop with new key
 
-                    self._record_usage(key_usage, model_id, 0)
+                    self._record_usage(key_usage, model_id, 0, track_usage)
                     raise
             else:
                 # Inner loop exhausted without success - continue to next key
@@ -209,7 +221,13 @@ class RotatingOpenAIClient(BaseRotatingClient):
 
         raise RuntimeError(f"All retry attempts exhausted for {model_id}")
 
-    def _wrap_stream(self, generator: Generator, key_usage: KeyUsage, model_id: str):
+    def _wrap_stream(
+        self,
+        generator: Generator,
+        key_usage: KeyUsage,
+        model_id: str,
+        track_usage: Optional[bool] = None,
+    ):
         final_tokens = 0
         try:
             for chunk in generator:
@@ -217,9 +235,9 @@ class RotatingOpenAIClient(BaseRotatingClient):
                     final_tokens = chunk.usage.total_tokens
                 yield chunk
         except Exception as e:
-            if is_payment_required_error(e):
+            if is_dead_key_error(e):
                 logger.warning(
-                    "402/PaymentRequired hit during streaming for %s on key ...%s. Marking key dead.",
+                    "Dead key (401/402/403) hit during streaming for %s on key ...%s. Marking key dead.",
                     model_id, get_key_suffix(key_usage.api_key)
                 )
                 key_usage.mark_dead()
@@ -233,7 +251,7 @@ class RotatingOpenAIClient(BaseRotatingClient):
                 self.manager.force_rotate_index()
             raise
         finally:
-            self._record_usage(key_usage, model_id, final_tokens)
+            self._record_usage(key_usage, model_id, final_tokens, track_usage)
 
 class SyncProxyHelper:
     def __init__(self, client: RotatingOpenAIClient, path: List[str]):
@@ -257,6 +275,9 @@ class RotatingAsyncOpenAIClient(BaseRotatingClient):
         return AsyncProxyHelper(self, [name])
 
     async def _execute(self, path: List[str], args, kwargs: dict):
+        # Per-call tracking override - popped before the kwargs reach the real
+        # OpenAI client, which rejects unknown keyword arguments.
+        track_usage = kwargs.pop('track_usage', None)
         model_id = kwargs.get('model', self.default_model)
         if 'model' not in kwargs:
             kwargs['model'] = model_id
@@ -266,9 +287,9 @@ class RotatingAsyncOpenAIClient(BaseRotatingClient):
             kwargs['stream_options'] = {"include_usage": True}
 
         for attempt in range(self.max_retries + 1):
-            key_usage = self.manager.get_key(model_id, limits, self.estimated_tokens)
+            key_usage = await self.manager.acquire_key_async(model_id, limits, self.estimated_tokens)
             if not key_usage:
-                raise RuntimeError(f"No available keys for {model_id}")
+                raise RuntimeError(self.manager.unavailable_message(model_id))
 
             # Create backoff for temporary rate limits
             temp_backoff = ExponentialBackoff(BackoffConfig(
@@ -288,9 +309,11 @@ class RotatingAsyncOpenAIClient(BaseRotatingClient):
                     result = await target(*args, **kwargs)
 
                     if kwargs.get('stream', False):
-                        return self._wrap_stream(result, key_usage, model_id)
+                        return self._wrap_stream(result, key_usage, model_id, track_usage)
 
-                    self._record_usage(key_usage, model_id, self._extract_usage(result))
+                    self._record_usage(
+                        key_usage, model_id, self._extract_usage(result), track_usage
+                    )
                     return result
 
                 except Exception as e:
@@ -305,11 +328,11 @@ class RotatingAsyncOpenAIClient(BaseRotatingClient):
                         await asyncio.sleep(delay)
                         continue  # Retry with SAME key
 
-                    # Payment required (quota/credits exhausted) - key is dead
+                    # Dead key (401/403 revoked/denied, 402 credits exhausted) - key is dead
                     # for this process, rotate to next key
-                    if is_payment_required_error(e) and attempt < self.max_retries:
+                    if is_dead_key_error(e) and attempt < self.max_retries:
                         logger.warning(
-                            "402/PaymentRequired hit for %s on key ...%s. Marking key dead and rotating. (Attempt %d/%d)",
+                            "Dead key (401/402/403) hit for %s on key ...%s. Marking key dead and rotating. (Attempt %d/%d)",
                             model_id, get_key_suffix(key_usage.api_key), attempt + 1, self.max_retries + 1
                         )
                         key_usage.mark_dead()
@@ -328,7 +351,7 @@ class RotatingAsyncOpenAIClient(BaseRotatingClient):
                         await asyncio.sleep(KEY_ROTATION_DELAY_SECONDS)
                         break  # Break inner loop, continue outer loop with new key
 
-                    self._record_usage(key_usage, model_id, 0)
+                    self._record_usage(key_usage, model_id, 0, track_usage)
                     raise
             else:
                 # Inner loop exhausted without success - continue to next key
@@ -343,7 +366,13 @@ class RotatingAsyncOpenAIClient(BaseRotatingClient):
 
         raise RuntimeError(f"All retry attempts exhausted for {model_id}")
 
-    async def _wrap_stream(self, generator: AsyncGenerator, key_usage: KeyUsage, model_id: str):
+    async def _wrap_stream(
+        self,
+        generator: AsyncGenerator,
+        key_usage: KeyUsage,
+        model_id: str,
+        track_usage: Optional[bool] = None,
+    ):
         final_tokens = 0
         try:
             async for chunk in generator:
@@ -351,9 +380,9 @@ class RotatingAsyncOpenAIClient(BaseRotatingClient):
                     final_tokens = chunk.usage.total_tokens
                 yield chunk
         except Exception as e:
-            if is_payment_required_error(e):
+            if is_dead_key_error(e):
                 logger.warning(
-                    "402/PaymentRequired hit during streaming for %s on key ...%s. Marking key dead.",
+                    "Dead key (401/402/403) hit during streaming for %s on key ...%s. Marking key dead.",
                     model_id, get_key_suffix(key_usage.api_key)
                 )
                 key_usage.mark_dead()
@@ -367,7 +396,7 @@ class RotatingAsyncOpenAIClient(BaseRotatingClient):
                 self.manager.force_rotate_index()
             raise
         finally:
-            self._record_usage(key_usage, model_id, final_tokens)
+            self._record_usage(key_usage, model_id, final_tokens, track_usage)
 
 class AsyncProxyHelper:
     def __init__(self, client: RotatingAsyncOpenAIClient, path: List[str]):

{keycycle-0.3.2 → keycycle-0.5.0}/keycycle/config/constants.py

@@ -31,5 +31,12 @@ TEMP_RATE_LIMIT_MULTIPLIER = 2.0
 # Key rotation delay (seconds to wait after rotating to a new key)
 KEY_ROTATION_DELAY_SECONDS = 0.5
 
+# How long acquire_key() polls for a live key to leave its rate window /
+# cooldown before giving up. A single production key at its per-minute cap
+# is the common case (Cohere, 2026-09-07): the right answer is to wait for
+# the window, not to abort the caller's whole run.
+KEY_WAIT_MAX_SECONDS = 120.0
+KEY_WAIT_POLL_SECONDS = 1.0
+
 # Usage logging batch size
 USAGE_LOG_BATCH_SIZE = 50

{keycycle-0.3.2 → keycycle-0.5.0}/keycycle/core/__init__.py

@@ -14,6 +14,7 @@ from .utils import (
     get_key_suffix,
     is_rate_limit_error,
     is_auth_error,
+    is_dead_key_error,
     validate_api_key,
 )
 from .backoff import ExponentialBackoff, BackoffConfig
@@ -33,6 +34,7 @@ __all__ = [
     "get_key_suffix",
     "is_rate_limit_error",
     "is_auth_error",
+    "is_dead_key_error",
     "validate_api_key",
     # Backoff
     "ExponentialBackoff",

{keycycle-0.3.2 → keycycle-0.5.0}/keycycle/core/utils.py

@@ -241,6 +241,29 @@ def is_auth_error(e: Exception) -> bool:
     return False
 
 
+# A key that answers 401/402/403 is unusable for good (revoked, unpaid,
+# or its project denied) — no cooldown will fix it, so rotate off it.
+DEAD_KEY_STATUS_CODES = AUTH_STATUS_CODES | PAYMENT_REQUIRED_STATUS_CODES
+
+
+def is_dead_key_error(e: Exception) -> bool:
+    """
+    Detect errors that mean THIS KEY is dead, not merely busy: HTTP 401/403
+    (invalid, revoked, or project-denied key — e.g. Gemini's
+    "Your project has been denied access") and 402 (credits exhausted).
+
+    A status_code, when present, is authoritative: 429s are never dead keys
+    whatever their message says. Without one, fall back to the string
+    heuristics of is_payment_required_error / is_auth_error.
+    """
+    status = getattr(e, "status_code", None)
+    if status in DEAD_KEY_STATUS_CODES:
+        return True
+    if status == 429:
+        return False
+    return is_payment_required_error(e) or is_auth_error(e)
+
+
 def validate_api_key(api_key: str) -> bool:
     """
     Basic validation of API key format.

{keycycle-0.3.2 → keycycle-0.5.0}/keycycle/key_rotation/rotating_mixin.py

@@ -15,7 +15,7 @@ from ..config.constants import (
 from ..core.utils import (
     is_rate_limit_error,
     is_temporary_rate_limit_error,
-    is_payment_required_error,
+    is_dead_key_error,
     get_key_suffix,
 )
 from ..core.backoff import ExponentialBackoff, BackoffConfig
@@ -115,7 +115,12 @@ class RotatingCredentialsMixin:
     def _get_retry_limit(self) -> int:
         return min(self._max_retries, len(self.wrapper.manager.keys) - 1)
 
-    def _record_usage(self, key_obj: KeyUsage, response: Optional["ModelResponse"]):
+    def _record_usage(
+        self,
+        key_obj: KeyUsage,
+        response: Optional["ModelResponse"],
+        track_usage: Optional[bool] = None,
+    ):
         """
         Extracts usage from the response and reports it to the manager.
         Falls back to estimated_tokens if response is None or usage is missing.
@@ -136,7 +141,8 @@ class RotatingCredentialsMixin:
             key_obj=key_obj,
             model_id=self.model_id,
             actual_tokens=actual_tokens,
-            estimated_tokens=self._estimated_tokens
+            estimated_tokens=self._estimated_tokens,
+            track_usage=track_usage
         )
 
     def _create_temp_backoff(self) -> ExponentialBackoff:
@@ -148,6 +154,9 @@ class RotatingCredentialsMixin:
         ))
 
     def invoke(self, *args, **kwargs) -> "ModelResponse":
+        # Per-call tracking override - popped before the kwargs reach the
+        # underlying model, which does not know this keyword.
+        track_usage = kwargs.pop("track_usage", None)
         limit = self._get_retry_limit()
 
         for attempt in range(limit + 1):
@@ -157,7 +166,7 @@ class RotatingCredentialsMixin:
             for temp_attempt in range(TEMP_RATE_LIMIT_MAX_RETRIES + 1):
                 try:
                     response = super().invoke(*args, **kwargs)
-                    self._record_usage(key_usage, response)
+                    self._record_usage(key_usage, response, track_usage)
                     return response
                 except Exception as e:
                     # Check for temporary rate limit first - retry with SAME key
@@ -171,11 +180,11 @@ class RotatingCredentialsMixin:
                         time.sleep(delay)
                         continue  # Retry with SAME key
 
-                    # Payment required (quota/credits exhausted) - key is dead
+                    # Dead key (401/403 revoked/denied, 402 credits exhausted) - key is dead
                     # for this process, rotate to next key
-                    if is_payment_required_error(e) and attempt < limit:
+                    if is_dead_key_error(e) and attempt < limit:
                         self.logger.warning(
-                            "402 Hit on key %s (Sync) [%s]. Marking key dead and rotating (%d/%d).",
+                            "Dead key (401/402/403) on key %s (Sync) [%s]. Marking key dead and rotating (%d/%d).",
                             get_key_suffix(self.api_key), self.model_id, attempt + 1, limit
                         )
                         key_usage.mark_dead()
@@ -205,6 +214,9 @@ class RotatingCredentialsMixin:
                 raise
 
     async def ainvoke(self, *args, **kwargs) -> "ModelResponse":
+        # Per-call tracking override - popped before the kwargs reach the
+        # underlying model, which does not know this keyword.
+        track_usage = kwargs.pop("track_usage", None)
         limit = self._get_retry_limit()
 
         for attempt in range(limit + 1):
@@ -214,7 +226,7 @@ class RotatingCredentialsMixin:
             for temp_attempt in range(TEMP_RATE_LIMIT_MAX_RETRIES + 1):
                 try:
                     response = await super().ainvoke(*args, **kwargs)
-                    self._record_usage(key_usage, response)
+                    self._record_usage(key_usage, response, track_usage)
                     return response
                 except Exception as e:
                     # Check for temporary rate limit first - retry with SAME key
@@ -228,11 +240,11 @@ class RotatingCredentialsMixin:
                         await asyncio.sleep(delay)
                         continue  # Retry with SAME key
 
-                    # Payment required (quota/credits exhausted) - key is dead
+                    # Dead key (401/403 revoked/denied, 402 credits exhausted) - key is dead
                     # for this process, rotate to next key
-                    if is_payment_required_error(e) and attempt < limit:
+                    if is_dead_key_error(e) and attempt < limit:
                         self.logger.warning(
-                            "402 Hit on key %s (Async) [%s]. Marking key dead and rotating (%d/%d).",
+                            "Dead key (401/402/403) on key %s (Async) [%s]. Marking key dead and rotating (%d/%d).",
                             get_key_suffix(self.api_key), self.model_id, attempt + 1, limit
                         )
                         key_usage.mark_dead()
@@ -262,6 +274,9 @@ class RotatingCredentialsMixin:
                 raise
 
     def invoke_stream(self, *args, **kwargs) -> Iterator["ModelResponse"]:
+        # Per-call tracking override - popped before the kwargs reach the
+        # underlying model, which does not know this keyword.
+        track_usage = kwargs.pop("track_usage", None)
         limit = self._get_retry_limit()
 
         for attempt in range(limit + 1):
@@ -280,10 +295,10 @@ class RotatingCredentialsMixin:
                         yield chunk
                     if final_usage:
                         dummy_response = _UsageResponse(final_usage)
-                        self._record_usage(key_usage, dummy_response)
+                        self._record_usage(key_usage, dummy_response, track_usage)
                     else:
                         # If the stream didn't return usage data, fallback to estimation
-                        self._record_usage(key_usage, None)
+                        self._record_usage(key_usage, None, track_usage)
 
                     return
                 except Exception as e:
@@ -300,9 +315,9 @@ class RotatingCredentialsMixin:
                         time.sleep(delay)
                         continue
 
-                    if is_payment_required_error(e) and attempt < limit:
+                    if is_dead_key_error(e) and attempt < limit:
                         self.logger.warning(
-                            "402 Hit on key %s (Sync Stream) [%s]. Marking key dead and rotating (%d/%d).",
+                            "Dead key (401/402/403) on key %s (Sync Stream) [%s]. Marking key dead and rotating (%d/%d).",
                             get_key_suffix(self.api_key), self.model_id, attempt + 1, limit
                         )
                         key_usage.mark_dead()
@@ -326,6 +341,9 @@ class RotatingCredentialsMixin:
                 raise
 
     async def ainvoke_stream(self, *args, **kwargs) -> AsyncIterator["ModelResponse"]:
+        # Per-call tracking override - popped before the kwargs reach the
+        # underlying model, which does not know this keyword.
+        track_usage = kwargs.pop("track_usage", None)
         limit = self._get_retry_limit()
 
         for attempt in range(limit + 1):
@@ -347,9 +365,9 @@ class RotatingCredentialsMixin:
                     # Stream completed successfully. Record usage.
                     if final_usage:
                         dummy_response = _UsageResponse(final_usage)
-                        self._record_usage(key_usage, dummy_response)
+                        self._record_usage(key_usage, dummy_response, track_usage)
                     else:
-                        self._record_usage(key_usage, None)
+                        self._record_usage(key_usage, None, track_usage)
 
                     return
                 except Exception as e:
@@ -366,9 +384,9 @@ class RotatingCredentialsMixin:
                         await asyncio.sleep(delay)
                         continue
 
-                    if is_payment_required_error(e) and attempt < limit:
+                    if is_dead_key_error(e) and attempt < limit:
                         self.logger.warning(
-                            "402 Hit on key %s (Async Stream) [%s]. Marking key dead and rotating (%d/%d).",
+                            "Dead key (401/402/403) on key %s (Async Stream) [%s]. Marking key dead and rotating (%d/%d).",
                             get_key_suffix(self.api_key), self.model_id, attempt + 1, limit
                         )
                         key_usage.mark_dead()