From 6764ab2673942e7a32a3a12414c5e7ecec64a8fa Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Mon, 14 Sep 2026 22:29:32 -0700
Subject: [PATCH 1/4] test(router): assert num_retries_per_request as a
 per-group cap that resets per fallback hop

#40930 (LIT-7505) changed num_retries_per_request from a request-wide
cap to a per-model-group cap that resets on every fallback hop, and its
own comment in litellm/__init__.py names that contract. The legacy
test_async_fallbacks_max_retries_per_request still asserted the old
request-wide reading (previous_models == 0), so the CircleCI router
suite has been red on main since that merge for every run-ci PR.

The test now reads the flat RetryAttemptRecord entries the fallback
call carries and asserts the new contract directly: every record is
from the first group, the retry at attempted_retries 0 is the real
AuthenticationError, and each later attempt was refused with
"Max retries per request hit!".
---
 tests/local_testing/test_router_fallbacks.py | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/tests/local_testing/test_router_fallbacks.py b/tests/local_testing/test_router_fallbacks.py
index 82b832f89fd..5d7955ad34a 100644
--- a/tests/local_testing/test_router_fallbacks.py
+++ b/tests/local_testing/test_router_fallbacks.py
@@ -5,6 +5,7 @@ import asyncio
 import os
 import time
 import traceback
+from typing import Final
 
 import pytest
 
@@ -13,6 +14,7 @@ from unittest.mock import AsyncMock, MagicMock, patch
 import litellm
 from litellm import Router
 from litellm.integrations.custom_logger import CustomLogger
+from litellm.types.router import RetryAttemptRecord
 
 from tests.fake_openai_endpoint import FAKE_OPENAI_API_BASE
 
@@ -21,15 +23,15 @@ class MyCustomHandler(CustomLogger):
     success: bool = False
     failure: bool = False
     previous_models: int = 0
+    previous_model_records: tuple[RetryAttemptRecord, ...] = ()
 
     def log_pre_api_call(self, model, messages, kwargs):
         print(f"Pre-API Call")
         print(
             f"previous_models: {kwargs['litellm_params']['metadata'].get('previous_models', None)}"
         )
-        self.previous_models = len(
-            kwargs["litellm_params"]["metadata"].get("previous_models", [])
-        )  # {"previous_models": [{"model": litellm_model_name, "exception_type": AuthenticationError, "exception_string": <complete_traceback>}]}
+        self.previous_model_records = tuple(kwargs["litellm_params"]["metadata"].get("previous_models", ()))
+        self.previous_models = len(self.previous_model_records)
         print(f"self.previous_models: {self.previous_models}")
 
     def log_post_api_call(self, kwargs, response_obj, start_time, end_time):
@@ -718,7 +720,14 @@ async def test_async_fallbacks_max_retries_per_request():
         await asyncio.sleep(
             0.05
         )  # allow a delay as success_callbacks are on a separate thread
-        assert customHandler.previous_models == 0  # 0 retries, 0 fallback
+        records: Final = customHandler.previous_model_records
+        assert customHandler.previous_models == len(records)
+        assert records
+        assert {record["model_group"] for record in records} == {"azure/gpt-3.5-turbo"}
+        assert next(record["exception_type"] for record in records if record["attempted_retries"] == 0) == "AuthenticationError"
+        refused_retries: Final = tuple(record for record in records if record["attempted_retries"])
+        assert refused_retries
+        assert all("Max retries per request hit!" in record["exception_string"] for record in refused_retries)
         router.reset()
     except litellm.Timeout as e:
         pass

From aaf924693a540572f90f512334ccbc056ce3554c Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Mon, 14 Sep 2026 23:13:50 -0700
Subject: [PATCH 2/4] fix(router): count num_retries_per_request across
 fallback hops

num_retries_per_request has always capped the retries of one request with its fallback hops included. #40930 started reading the per-hop attempted_retries counter instead, and every fallback hop restarts that counter at zero, so a request could spend a fresh retry budget on each hop and the legacy fallback cap test started seeing the hop run.

Router.log_retry now also keeps request_retry_count on the request metadata, incremented on every retry and fallback hop and never truncated the way previous_models is, and max_retries_per_request_hit reads that count. The flat retry records, the litellm_metadata coverage and caps above four from #40930 stay as they are, and the legacy test goes back to its previous_models == 0 assertion.
---
 litellm/__init__.py                           |  2 +-
 litellm/litellm_core_utils/core_helpers.py    |  4 +-
 litellm/router.py                             |  6 ++-
 tests/local_testing/test_router_fallbacks.py  | 17 ++----
 .../test_router_helper_utils.py               | 10 ++--
 .../rust_bridge/test_lifecycle.py             | 11 ++--
 tests/test_litellm/test_router.py             | 52 +++++++++++++++++++
 tests/test_litellm/test_utils.py              | 13 ++---
 8 files changed, 85 insertions(+), 30 deletions(-)

diff --git a/litellm/__init__.py b/litellm/__init__.py
index 261457d6889..ccfbf80369f 100644
--- a/litellm/__init__.py
+++ b/litellm/__init__.py
@@ -538,7 +538,7 @@ context_window_fallbacks: Optional[List] = None
 content_policy_fallbacks: Optional[List] = None
 allowed_fails: int = 3
 allow_dynamic_callback_disabling: bool = True
-num_retries_per_request: Optional[int] = None  # cap on Router retries of one model group; resets per fallback hop
+num_retries_per_request: Optional[int] = None  # for the request overall (incl. fallbacks + model retries)
 ####### SECRET MANAGERS #####################
 secret_manager_client: Optional[Any] = (
     None  # list of instantiated key management clients - e.g. azure kv, infisical, etc.
diff --git a/litellm/litellm_core_utils/core_helpers.py b/litellm/litellm_core_utils/core_helpers.py
index 6e76bf9d49e..15380bc5d57 100644
--- a/litellm/litellm_core_utils/core_helpers.py
+++ b/litellm/litellm_core_utils/core_helpers.py
@@ -309,8 +309,8 @@ def max_retries_per_request_hit(kwargs: Mapping[str, object], num_retries_per_re
     metadata: Final = kwargs.get(get_metadata_variable_name_from_kwargs(kwargs))
     if not isinstance(metadata, Mapping):
         return False
-    attempted_retries: Final = metadata.get("attempted_retries")
-    return type(attempted_retries) is int and 0 < attempted_retries and num_retries_per_request <= attempted_retries
+    retry_count: Final = metadata.get("request_retry_count")
+    return type(retry_count) is int and 0 < retry_count and num_retries_per_request <= retry_count
 
 
 def get_or_create_metadata_bucket(
diff --git a/litellm/router.py b/litellm/router.py
index 1665583386f..ff50cac1328 100644
--- a/litellm/router.py
+++ b/litellm/router.py
@@ -8378,7 +8378,8 @@ class Router:
 
     def log_retry(self, kwargs: dict, e: Exception) -> dict:
         """
-        When a retry or fallback happens, record which model group, deployment and attempt just failed and why
+        When a retry or fallback happens, record which model group, deployment and attempt just failed and why,
+        and count it toward the request-wide num_retries_per_request cap
         """
         from litellm.types.router import RetryAttemptRecord
 
@@ -8402,7 +8403,10 @@ class Router:
             else ()
         )
         breadcrumbs: Final = (*kept_breadcrumbs, attempt_record)
+        earlier_retry_count: Final = request_metadata.get("request_retry_count")
+        request_retry_count: Final = (earlier_retry_count if type(earlier_retry_count) is int else 0) + 1
         kwargs[_metadata_var]["previous_models"] = breadcrumbs  # rebind-ok: the logging object already holds this dict
+        kwargs[_metadata_var]["request_retry_count"] = request_retry_count  # rebind-ok: same dict, read by the cap
         return kwargs
 
     def _update_usage(self, deployment_id: str, parent_otel_span: Span | None) -> int:
diff --git a/tests/local_testing/test_router_fallbacks.py b/tests/local_testing/test_router_fallbacks.py
index 5d7955ad34a..82b832f89fd 100644
--- a/tests/local_testing/test_router_fallbacks.py
+++ b/tests/local_testing/test_router_fallbacks.py
@@ -5,7 +5,6 @@ import asyncio
 import os
 import time
 import traceback
-from typing import Final
 
 import pytest
 
@@ -14,7 +13,6 @@ from unittest.mock import AsyncMock, MagicMock, patch
 import litellm
 from litellm import Router
 from litellm.integrations.custom_logger import CustomLogger
-from litellm.types.router import RetryAttemptRecord
 
 from tests.fake_openai_endpoint import FAKE_OPENAI_API_BASE
 
@@ -23,15 +21,15 @@ class MyCustomHandler(CustomLogger):
     success: bool = False
     failure: bool = False
     previous_models: int = 0
-    previous_model_records: tuple[RetryAttemptRecord, ...] = ()
 
     def log_pre_api_call(self, model, messages, kwargs):
         print(f"Pre-API Call")
         print(
             f"previous_models: {kwargs['litellm_params']['metadata'].get('previous_models', None)}"
         )
-        self.previous_model_records = tuple(kwargs["litellm_params"]["metadata"].get("previous_models", ()))
-        self.previous_models = len(self.previous_model_records)
+        self.previous_models = len(
+            kwargs["litellm_params"]["metadata"].get("previous_models", [])
+        )  # {"previous_models": [{"model": litellm_model_name, "exception_type": AuthenticationError, "exception_string": <complete_traceback>}]}
         print(f"self.previous_models: {self.previous_models}")
 
     def log_post_api_call(self, kwargs, response_obj, start_time, end_time):
@@ -720,14 +718,7 @@ async def test_async_fallbacks_max_retries_per_request():
         await asyncio.sleep(
             0.05
         )  # allow a delay as success_callbacks are on a separate thread
-        records: Final = customHandler.previous_model_records
-        assert customHandler.previous_models == len(records)
-        assert records
-        assert {record["model_group"] for record in records} == {"azure/gpt-3.5-turbo"}
-        assert next(record["exception_type"] for record in records if record["attempted_retries"] == 0) == "AuthenticationError"
-        refused_retries: Final = tuple(record for record in records if record["attempted_retries"])
-        assert refused_retries
-        assert all("Max retries per request hit!" in record["exception_string"] for record in refused_retries)
+        assert customHandler.previous_models == 0  # 0 retries, 0 fallback
         router.reset()
     except litellm.Timeout as e:
         pass
diff --git a/tests/router_unit_tests/test_router_helper_utils.py b/tests/router_unit_tests/test_router_helper_utils.py
index 5b06c5fdb01..c7e577366c3 100644
--- a/tests/router_unit_tests/test_router_helper_utils.py
+++ b/tests/router_unit_tests/test_router_helper_utils.py
@@ -631,9 +631,11 @@ def test_deployment_callback_respects_cooldown_time(model_list):
 
 @pytest.mark.parametrize("metadata_key", ["metadata", "litellm_metadata"])
 def test_log_retry(model_list, metadata_key):
-    """log_retry appends one flat record per failed attempt and copies neither the request kwargs nor
-    the request metadata into it"""
+    """log_retry appends one flat record per failed attempt, copies neither the request kwargs nor the
+    request metadata into it, and counts every failed attempt of the request independently of the
+    per-hop attempted_retries"""
     router = Router(model_list=model_list)
+    rate_limit_error = litellm.RateLimitError(message="slow down", llm_provider="openai", model="gpt-3.5-turbo")
     new_kwargs = router.log_retry(
         kwargs={
             "model": "gpt-3.5-turbo",
@@ -641,7 +643,7 @@ def test_log_retry(model_list, metadata_key):
             "messages": [{"role": "user", "content": "hi"}],
             metadata_key: {"model_info": {"id": "deployment-1"}, "attempted_retries": 2, "user_api_key": "sk-proxy"},
         },
-        e=litellm.RateLimitError(message="slow down", llm_provider="openai", model="gpt-3.5-turbo"),
+        e=rate_limit_error,
     )
     assert json.loads(json.dumps(new_kwargs[metadata_key]["previous_models"])) == [
         {
@@ -652,6 +654,8 @@ def test_log_retry(model_list, metadata_key):
             "attempted_retries": 2,
         }
     ]
+    assert new_kwargs[metadata_key]["request_retry_count"] == 1
+    assert router.log_retry(kwargs=new_kwargs, e=rate_limit_error)[metadata_key]["request_retry_count"] == 2
 
 
 def test_update_usage(model_list):
diff --git a/tests/test_litellm/rust_bridge/test_lifecycle.py b/tests/test_litellm/rust_bridge/test_lifecycle.py
index 1f0b5591c2b..d73385621d5 100644
--- a/tests/test_litellm/rust_bridge/test_lifecycle.py
+++ b/tests/test_litellm/rust_bridge/test_lifecycle.py
@@ -8,7 +8,7 @@ from litellm.rust_bridge.lifecycle import check_limits
 
 @pytest.mark.parametrize("metadata_key", ["metadata", "litellm_metadata"])
 @pytest.mark.parametrize(
-    "cap, attempted_retries, refused",
+    "cap, request_retry_count, refused",
     [(5, 5, True), (5, 4, False), (0, 0, False), (0, 1, True)],
     ids=[
         "cap-above-four-reached",
@@ -17,12 +17,15 @@ from litellm.rust_bridge.lifecycle import check_limits
         "cap-of-zero-refuses-first-retry",
     ],
 )
-def test_check_limits_reads_attempted_retries(
-    monkeypatch: pytest.MonkeyPatch, metadata_key: str, cap: int, attempted_retries: int, refused: bool
+def test_check_limits_reads_request_retry_count(
+    monkeypatch: pytest.MonkeyPatch, metadata_key: str, cap: int, request_retry_count: int, refused: bool
 ) -> None:
     monkeypatch.setattr(litellm, "num_retries_per_request", cap)
     monkeypatch.setattr(litellm, "max_budget", None)
-    kwargs: Final = {"model": "mistral/mistral-ocr-latest", metadata_key: {"attempted_retries": attempted_retries}}
+    kwargs: Final = {
+        "model": "mistral/mistral-ocr-latest",
+        metadata_key: {"request_retry_count": request_retry_count},
+    }
     if refused:
         with pytest.raises(RuntimeError, match="Max retries per request hit!"):
             check_limits(kwargs)
diff --git a/tests/test_litellm/test_router.py b/tests/test_litellm/test_router.py
index 3cabcd71627..577332727d7 100644
--- a/tests/test_litellm/test_router.py
+++ b/tests/test_litellm/test_router.py
@@ -11066,6 +11066,58 @@ async def test_num_retries_per_request_stops_retries_at_caps_above_four(monkeypa
     ]
 
 
+def _failing_group_with_healthy_fallback_router(num_retries):
+    return litellm.Router(
+        model_list=[
+            {
+                "model_name": "broken-group",
+                "litellm_params": {
+                    "model": "openai/gpt-4o-mini",
+                    "api_key": "sk-fake",
+                    "mock_response": "litellm.InternalServerError",
+                },
+            },
+            {
+                "model_name": "healthy-group",
+                "litellm_params": {"model": "openai/gpt-4o-mini", "api_key": "sk-fake", "mock_response": "ok"},
+            },
+        ],
+        fallbacks=[{"broken-group": ["healthy-group"]}],
+        num_retries=num_retries,
+    )
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "cap, hop_refused", [(2, True), (4, False)], ids=["cap-spent-before-the-hop", "cap-not-reached-by-the-hop"]
+)
+async def test_num_retries_per_request_counts_retries_across_fallback_hops(monkeypatch, cap, hop_refused):
+    """num_retries_per_request caps the retries of one request, fallback hops included. Each hop starts a
+    fresh per-hop attempted_retries at zero, so a cap read from that counter let every hop retry from zero
+    and a request could spend far more retries than the cap allows."""
+    monkeypatch.setattr(litellm, "num_retries_per_request", cap)
+    router = _failing_group_with_healthy_fallback_router(num_retries=1)
+    recorder = _FallbackAttemptRecorder()
+    litellm.callbacks.append(recorder)
+    try:
+        request = router.acompletion(model="broken-group", messages=[{"role": "user", "content": "hi"}])
+        if not hop_refused:
+            assert (await request).choices[0].message.content == "ok"
+            return
+        with pytest.raises(litellm.InternalServerError):
+            await request
+    finally:
+        litellm.callbacks.remove(recorder)
+
+    assert recorder.failed_targets == ["healthy-group"]
+    hop_refusals = [
+        record["attempted_retries"]
+        for record in recorder.breadcrumbs_per_target[0]
+        if record["model_group"] == "healthy-group" and "Max retries per request hit!" in record["exception_string"]
+    ]
+    assert hop_refusals == [0, 1]
+
+
 @pytest.mark.asyncio
 async def test_fallback_traceback_stays_available_at_debug_level():
     """Dropping the stack from the ERROR line is only safe because the fallback path still
diff --git a/tests/test_litellm/test_utils.py b/tests/test_litellm/test_utils.py
index d5feda6f892..3d60fe86d9c 100644
--- a/tests/test_litellm/test_utils.py
+++ b/tests/test_litellm/test_utils.py
@@ -4077,10 +4077,11 @@ class TestMetadataNoneHandling:
 
 
 _RETRY_CAP_CASES: Final = (
-    pytest.param(5, {"attempted_retries": 5}, True, id="cap-above-four-reached"),
-    pytest.param(5, {"attempted_retries": 4}, False, id="cap-above-four-not-reached"),
-    pytest.param(0, {"attempted_retries": 0}, False, id="first-attempt-passes-cap-of-zero"),
-    pytest.param(0, {"attempted_retries": 1}, True, id="cap-of-zero-refuses-first-retry"),
+    pytest.param(5, {"request_retry_count": 5}, True, id="cap-above-four-reached"),
+    pytest.param(5, {"request_retry_count": 4}, False, id="cap-above-four-not-reached"),
+    pytest.param(0, {"request_retry_count": 0}, False, id="first-attempt-passes-cap-of-zero"),
+    pytest.param(0, {"request_retry_count": 1}, True, id="cap-of-zero-refuses-first-retry"),
+    pytest.param(0, {"attempted_retries": 1}, False, id="per-hop-attempted-retries-is-not-the-cap"),
     pytest.param(5, {"previous_models": ("a", "b", "c", "d", "e")}, False, id="breadcrumb-count-is-not-the-cap"),
     pytest.param(5, None, False, id="metadata-none"),
 )
@@ -4098,7 +4099,7 @@ def _capped_completion_kwargs(metadata_key: str, metadata: object) -> dict[str,
 
 @pytest.mark.parametrize("metadata_key", ["metadata", "litellm_metadata"])
 @pytest.mark.parametrize("cap, metadata, refused", _RETRY_CAP_CASES)
-def test_num_retries_per_request_reads_attempted_retries_sync(monkeypatch, metadata_key, cap, metadata, refused):
+def test_num_retries_per_request_reads_request_retry_count_sync(monkeypatch, metadata_key, cap, metadata, refused):
     monkeypatch.setattr(litellm, "num_retries_per_request", cap)
     kwargs: Final = _capped_completion_kwargs(metadata_key, metadata)
     if refused:
@@ -4111,7 +4112,7 @@ def test_num_retries_per_request_reads_attempted_retries_sync(monkeypatch, metad
 @pytest.mark.asyncio
 @pytest.mark.parametrize("metadata_key", ["metadata", "litellm_metadata"])
 @pytest.mark.parametrize("cap, metadata, refused", _RETRY_CAP_CASES)
-async def test_num_retries_per_request_reads_attempted_retries_async(monkeypatch, metadata_key, cap, metadata, refused):
+async def test_num_retries_per_request_reads_request_retry_count_async(monkeypatch, metadata_key, cap, metadata, refused):
     monkeypatch.setattr(litellm, "num_retries_per_request", cap)
     kwargs: Final = _capped_completion_kwargs(metadata_key, metadata)
     if refused:

From f80cb5cb4676a9d49009aef432cc9f5eda5ed15b Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Tue, 15 Sep 2026 00:04:02 -0700
Subject: [PATCH 3/4] fix(router): ignore planted request_retry_count seeds and
 cover the rust OCR cap path

The router clamps a negative request_retry_count found in request metadata before counting a failure, and the proxy strips a client-supplied request_retry_count with the other router-reserved metadata fields. The rust OCR lifecycle test that trips the per-request cap now plants request_retry_count instead of attempted_retries, which the cap no longer reads since the previous commit
---
 litellm/proxy/litellm_pre_call_utils.py          |  2 +-
 litellm/router.py                                |  4 ++--
 .../test_router_helper_utils.py                  |  6 ++++--
 .../proxy/test_litellm_pre_call_utils.py         |  4 ++++
 tests/test_litellm/test_router.py                | 16 ++++++++++++----
 tests/test_litellm_rust/ocr/test_lifecycle.py    |  2 +-
 6 files changed, 24 insertions(+), 10 deletions(-)

diff --git a/litellm/proxy/litellm_pre_call_utils.py b/litellm/proxy/litellm_pre_call_utils.py
index 59971e54e46..14d0e7e478f 100644
--- a/litellm/proxy/litellm_pre_call_utils.py
+++ b/litellm/proxy/litellm_pre_call_utils.py
@@ -334,7 +334,7 @@ _CLIENT_PRICING_METADATA_FIELDS: Final = frozenset({"model_info", "standard_logg
 # and read by spend logs as fact; a client value has no legitimate meaning and no
 # key or team setting keeps it, so the strip is never gated.
 _ROUTER_RESERVED_METADATA_FIELDS: Final = frozenset(
-    {"attempted_fallbacks", "original_model_group", CLIENT_OUTPUT_CEILING_METADATA_KEY}
+    {"attempted_fallbacks", "original_model_group", "request_retry_count", CLIENT_OUTPUT_CEILING_METADATA_KEY}
 )
 _ALLOW_CLIENT_PRICING_OVERRIDE_METADATA_KEY: Final = "allow_client_pricing_override"
 
diff --git a/litellm/router.py b/litellm/router.py
index ff50cac1328..cb0b7050876 100644
--- a/litellm/router.py
+++ b/litellm/router.py
@@ -8403,8 +8403,8 @@ class Router:
             else ()
         )
         breadcrumbs: Final = (*kept_breadcrumbs, attempt_record)
-        earlier_retry_count: Final = request_metadata.get("request_retry_count")
-        request_retry_count: Final = (earlier_retry_count if type(earlier_retry_count) is int else 0) + 1
+        earlier: Final = request_metadata.get("request_retry_count")
+        request_retry_count: Final = (earlier if type(earlier) is int and 0 <= earlier else 0) + 1
         kwargs[_metadata_var]["previous_models"] = breadcrumbs  # rebind-ok: the logging object already holds this dict
         kwargs[_metadata_var]["request_retry_count"] = request_retry_count  # rebind-ok: same dict, read by the cap
         return kwargs
diff --git a/tests/router_unit_tests/test_router_helper_utils.py b/tests/router_unit_tests/test_router_helper_utils.py
index c7e577366c3..7949dd7818d 100644
--- a/tests/router_unit_tests/test_router_helper_utils.py
+++ b/tests/router_unit_tests/test_router_helper_utils.py
@@ -632,8 +632,8 @@ def test_deployment_callback_respects_cooldown_time(model_list):
 @pytest.mark.parametrize("metadata_key", ["metadata", "litellm_metadata"])
 def test_log_retry(model_list, metadata_key):
     """log_retry appends one flat record per failed attempt, copies neither the request kwargs nor the
-    request metadata into it, and counts every failed attempt of the request independently of the
-    per-hop attempted_retries"""
+    request metadata into it, counts every failed attempt of the request independently of the
+    per-hop attempted_retries, and never trusts a negative count planted before the first failure"""
     router = Router(model_list=model_list)
     rate_limit_error = litellm.RateLimitError(message="slow down", llm_provider="openai", model="gpt-3.5-turbo")
     new_kwargs = router.log_retry(
@@ -656,6 +656,8 @@ def test_log_retry(model_list, metadata_key):
     ]
     assert new_kwargs[metadata_key]["request_retry_count"] == 1
     assert router.log_retry(kwargs=new_kwargs, e=rate_limit_error)[metadata_key]["request_retry_count"] == 2
+    planted_kwargs = {"model": "gpt-3.5-turbo", metadata_key: {"request_retry_count": -100}}
+    assert router.log_retry(kwargs=planted_kwargs, e=rate_limit_error)[metadata_key]["request_retry_count"] == 1
 
 
 def test_update_usage(model_list):
diff --git a/tests/test_litellm/proxy/test_litellm_pre_call_utils.py b/tests/test_litellm/proxy/test_litellm_pre_call_utils.py
index 37b983d709a..abd59bb4d3b 100644
--- a/tests/test_litellm/proxy/test_litellm_pre_call_utils.py
+++ b/tests/test_litellm/proxy/test_litellm_pre_call_utils.py
@@ -7346,6 +7346,7 @@ def _reserved_stamp_key(key_metadata: dict | None = None) -> UserAPIKeyAuth:
 _PLANTED_STAMPS = {
     "attempted_fallbacks": 99,
     "original_model_group": "spoofed-group",
+    "request_retry_count": -100,
     "_client_output_ceiling": {"api_base": "https://attacker.example"},
     "client_key": "client_value",
 }
@@ -7378,6 +7379,7 @@ async def test_add_litellm_data_to_request_strips_router_reserved_stamps_from_bo
     assert "attempted_fallbacks" not in updated["metadata"]
     assert "original_model_group" not in updated["metadata"]
     assert "_client_output_ceiling" not in updated["metadata"]
+    assert "request_retry_count" not in updated["metadata"]
     assert updated["metadata"]["client_key"] == "client_value"
 
 
@@ -7403,6 +7405,7 @@ async def test_add_litellm_data_to_request_strips_router_reserved_stamps_from_js
     assert "litellm_metadata" not in updated
     assert "attempted_fallbacks" not in updated["metadata"]
     assert "original_model_group" not in updated["metadata"]
+    assert "request_retry_count" not in updated["metadata"]
     assert updated["metadata"]["client_key"] == "client_value"
 
 
@@ -7431,6 +7434,7 @@ async def test_add_litellm_data_to_request_strips_router_reserved_stamps_despite
     assert updated["metadata"]["model_info"] == {"input_cost_per_token": 0.0}
     assert "attempted_fallbacks" not in updated["metadata"]
     assert "original_model_group" not in updated["metadata"]
+    assert "request_retry_count" not in updated["metadata"]
 
 
 @pytest.mark.asyncio
diff --git a/tests/test_litellm/test_router.py b/tests/test_litellm/test_router.py
index 577332727d7..1de86084980 100644
--- a/tests/test_litellm/test_router.py
+++ b/tests/test_litellm/test_router.py
@@ -11089,18 +11089,26 @@ def _failing_group_with_healthy_fallback_router(num_retries):
 
 @pytest.mark.asyncio
 @pytest.mark.parametrize(
-    "cap, hop_refused", [(2, True), (4, False)], ids=["cap-spent-before-the-hop", "cap-not-reached-by-the-hop"]
+    "cap, planted_count, hop_refused",
+    [(2, None, True), (4, None, False), (2, -100, True)],
+    ids=["cap-spent-before-the-hop", "cap-not-reached-by-the-hop", "planted-negative-count-does-not-lift-the-cap"],
 )
-async def test_num_retries_per_request_counts_retries_across_fallback_hops(monkeypatch, cap, hop_refused):
+async def test_num_retries_per_request_counts_retries_across_fallback_hops(
+    monkeypatch, cap, planted_count, hop_refused
+):
     """num_retries_per_request caps the retries of one request, fallback hops included. Each hop starts a
     fresh per-hop attempted_retries at zero, so a cap read from that counter let every hop retry from zero
-    and a request could spend far more retries than the cap allows."""
+    and a request could spend far more retries than the cap allows. A caller who plants a negative count
+    in the request metadata must not push the cap further away either."""
     monkeypatch.setattr(litellm, "num_retries_per_request", cap)
     router = _failing_group_with_healthy_fallback_router(num_retries=1)
     recorder = _FallbackAttemptRecorder()
     litellm.callbacks.append(recorder)
     try:
-        request = router.acompletion(model="broken-group", messages=[{"role": "user", "content": "hi"}])
+        metadata = {} if planted_count is None else {"request_retry_count": planted_count}
+        request = router.acompletion(
+            model="broken-group", messages=[{"role": "user", "content": "hi"}], metadata=metadata
+        )
         if not hop_refused:
             assert (await request).choices[0].message.content == "ok"
             return
diff --git a/tests/test_litellm_rust/ocr/test_lifecycle.py b/tests/test_litellm_rust/ocr/test_lifecycle.py
index 77d9ef167d0..dfcd63d3019 100644
--- a/tests/test_litellm_rust/ocr/test_lifecycle.py
+++ b/tests/test_litellm_rust/ocr/test_lifecycle.py
@@ -806,7 +806,7 @@ async def test_shared_call_limits_still_reject_before_reading_ocr_file(
     monkeypatch.setattr(litellm, "_current_cost", 2)
     monkeypatch.setattr(litellm, "num_retries_per_request", 1 if limit == "retries" else None)
     expected: Final = litellm.BudgetExceededError if limit == "budget" else RuntimeError
-    arguments: Final = {"document": {"type": "file", "file": File()}, "metadata": {"attempted_retries": 1}}
+    arguments: Final = {"document": {"type": "file", "file": File()}, "metadata": {"request_retry_count": 1}}
     with pytest.raises(expected, match=r"Budget has been exceeded|Max retries per request hit"):
         await call_aocr(ocr_server, **arguments) if asynchronous else call_ocr(ocr_server, **arguments)
     assert reads == []

From 1b040af41456d1c59019c121ead990b005159e2f Mon Sep 17 00:00:00 2001
From: mateo-berri <277851410+mateo-berri@users.noreply.github.com>
Date: Tue, 15 Sep 2026 00:34:38 -0700
Subject: [PATCH 4/4] test(router): type the retry-cap tests this PR adds or
 touches

---
 tests/router_unit_tests/test_router_helper_utils.py     | 4 ++--
 tests/test_litellm/proxy/test_litellm_pre_call_utils.py | 6 +++---
 tests/test_litellm/test_router.py                       | 6 +++---
 tests/test_litellm/test_utils.py                        | 8 ++++++--
 4 files changed, 14 insertions(+), 10 deletions(-)

diff --git a/tests/router_unit_tests/test_router_helper_utils.py b/tests/router_unit_tests/test_router_helper_utils.py
index 7949dd7818d..b18bf9351c8 100644
--- a/tests/router_unit_tests/test_router_helper_utils.py
+++ b/tests/router_unit_tests/test_router_helper_utils.py
@@ -11,7 +11,7 @@ import litellm
 from unittest.mock import patch, MagicMock, AsyncMock
 from create_mock_standard_logging_payload import create_standard_logging_payload
 from litellm.types.utils import StandardLoggingPayload
-from litellm.types.router import Deployment, LiteLLM_Params, ModelInfo
+from litellm.types.router import Deployment, DeploymentTypedDict, LiteLLM_Params, ModelInfo
 from litellm.constants import DEFAULT_AUTO_ROUTER_MAX_INPUT_CHARS
 
 
@@ -630,7 +630,7 @@ def test_deployment_callback_respects_cooldown_time(model_list):
 
 
 @pytest.mark.parametrize("metadata_key", ["metadata", "litellm_metadata"])
-def test_log_retry(model_list, metadata_key):
+def test_log_retry(model_list: list[DeploymentTypedDict], metadata_key: str) -> None:
     """log_retry appends one flat record per failed attempt, copies neither the request kwargs nor the
     request metadata into it, counts every failed attempt of the request independently of the
     per-hop attempted_retries, and never trusts a negative count planted before the first failure"""
diff --git a/tests/test_litellm/proxy/test_litellm_pre_call_utils.py b/tests/test_litellm/proxy/test_litellm_pre_call_utils.py
index abd59bb4d3b..a2b261dcfb0 100644
--- a/tests/test_litellm/proxy/test_litellm_pre_call_utils.py
+++ b/tests/test_litellm/proxy/test_litellm_pre_call_utils.py
@@ -7353,7 +7353,7 @@ _PLANTED_STAMPS = {
 
 
 @pytest.mark.asyncio
-async def test_add_litellm_data_to_request_strips_router_reserved_stamps_from_both_buckets():
+async def test_add_litellm_data_to_request_strips_router_reserved_stamps_from_both_buckets() -> None:
     """attempted_fallbacks and original_model_group are router-written facts the spend row
     reads back; a client planting them in either bucket is dropped at the boundary so the
     router never sees a reserved key it did not write."""
@@ -7384,7 +7384,7 @@ async def test_add_litellm_data_to_request_strips_router_reserved_stamps_from_bo
 
 
 @pytest.mark.asyncio
-async def test_add_litellm_data_to_request_strips_router_reserved_stamps_from_json_string_litellm_metadata():
+async def test_add_litellm_data_to_request_strips_router_reserved_stamps_from_json_string_litellm_metadata() -> None:
     from litellm.proxy.litellm_pre_call_utils import add_litellm_data_to_request
 
     data = {
@@ -7410,7 +7410,7 @@ async def test_add_litellm_data_to_request_strips_router_reserved_stamps_from_js
 
 
 @pytest.mark.asyncio
-async def test_add_litellm_data_to_request_strips_router_reserved_stamps_despite_pricing_override_opt_in():
+async def test_add_litellm_data_to_request_strips_router_reserved_stamps_despite_pricing_override_opt_in() -> None:
     """The pricing strip is gated on allow_client_pricing_override; the reserved-stamp strip
     is not, because no key or team setting makes a client-written fallback count valid."""
     from litellm.proxy.litellm_pre_call_utils import add_litellm_data_to_request
diff --git a/tests/test_litellm/test_router.py b/tests/test_litellm/test_router.py
index 1de86084980..0485da3eba9 100644
--- a/tests/test_litellm/test_router.py
+++ b/tests/test_litellm/test_router.py
@@ -11066,7 +11066,7 @@ async def test_num_retries_per_request_stops_retries_at_caps_above_four(monkeypa
     ]
 
 
-def _failing_group_with_healthy_fallback_router(num_retries):
+def _failing_group_with_healthy_fallback_router(num_retries: int) -> litellm.Router:
     return litellm.Router(
         model_list=[
             {
@@ -11094,8 +11094,8 @@ def _failing_group_with_healthy_fallback_router(num_retries):
     ids=["cap-spent-before-the-hop", "cap-not-reached-by-the-hop", "planted-negative-count-does-not-lift-the-cap"],
 )
 async def test_num_retries_per_request_counts_retries_across_fallback_hops(
-    monkeypatch, cap, planted_count, hop_refused
-):
+    monkeypatch: pytest.MonkeyPatch, cap: int, planted_count: int | None, hop_refused: bool
+) -> None:
     """num_retries_per_request caps the retries of one request, fallback hops included. Each hop starts a
     fresh per-hop attempted_retries at zero, so a cap read from that counter let every hop retry from zero
     and a request could spend far more retries than the cap allows. A caller who plants a negative count
diff --git a/tests/test_litellm/test_utils.py b/tests/test_litellm/test_utils.py
index 3d60fe86d9c..e7878f6bff0 100644
--- a/tests/test_litellm/test_utils.py
+++ b/tests/test_litellm/test_utils.py
@@ -4099,7 +4099,9 @@ def _capped_completion_kwargs(metadata_key: str, metadata: object) -> dict[str,
 
 @pytest.mark.parametrize("metadata_key", ["metadata", "litellm_metadata"])
 @pytest.mark.parametrize("cap, metadata, refused", _RETRY_CAP_CASES)
-def test_num_retries_per_request_reads_request_retry_count_sync(monkeypatch, metadata_key, cap, metadata, refused):
+def test_num_retries_per_request_reads_request_retry_count_sync(
+    monkeypatch: pytest.MonkeyPatch, metadata_key: str, cap: int, metadata: object, refused: bool
+) -> None:
     monkeypatch.setattr(litellm, "num_retries_per_request", cap)
     kwargs: Final = _capped_completion_kwargs(metadata_key, metadata)
     if refused:
@@ -4112,7 +4114,9 @@ def test_num_retries_per_request_reads_request_retry_count_sync(monkeypatch, met
 @pytest.mark.asyncio
 @pytest.mark.parametrize("metadata_key", ["metadata", "litellm_metadata"])
 @pytest.mark.parametrize("cap, metadata, refused", _RETRY_CAP_CASES)
-async def test_num_retries_per_request_reads_request_retry_count_async(monkeypatch, metadata_key, cap, metadata, refused):
+async def test_num_retries_per_request_reads_request_retry_count_async(
+    monkeypatch: pytest.MonkeyPatch, metadata_key: str, cap: int, metadata: object, refused: bool
+) -> None:
     monkeypatch.setattr(litellm, "num_retries_per_request", cap)
     kwargs: Final = _capped_completion_kwargs(metadata_key, metadata)
     if refused: