fix(retry): align REST max_retries to count retries not total attempts

REST `_RetryTransport` and `_AsyncRetryTransport` previously looped
`range(max_retries)`, making `max_retries` the *total* attempt count
(initial + retries). gRPC counts retries only, so the same
`RetryConfig(max_retries=N)` gave different behavior per transport.

Change the loops to `range(max_retries + 1)` and update the
last-attempt guards from `attempt < max_retries - 1` to
`attempt < max_retries` so both transports treat `max_retries` as the
number of retries after the initial attempt.

Also update the `RetryConfig.max_retries` docstring and all unit tests
that hard-coded expected call counts under the old semantics.

Author: jhamon

pinecone/_internal/config.py

@@ -79,7 +79,7 @@ class RetryConfig:
     """Configuration for HTTP retry behavior.
 
     Args:
-        max_retries: Total number of request attempts (initial + retries). Defaults to 3.
+        max_retries: Number of retries after the initial attempt. Defaults to 3 (4 total attempts).
         backoff_factor: Exponential backoff base multiplier in seconds. Defaults to 2.0.
         max_wait: Maximum backoff delay in seconds. Defaults to 60.0.
         retryable_status_codes: HTTP status codes that trigger a retry. Defaults to

pinecone/_internal/http_client.py

@@ -131,16 +131,16 @@ def __init__(
 
     def handle_request(self, request: httpx.Request) -> httpx.Response:
         last_exc: httpx.TransportError | None = None
-        for attempt in range(self._config.max_retries):
+        for attempt in range(self._config.max_retries + 1):
             try:
                 response = self._transport.handle_request(request)
             except httpx.TransportError as exc:
                 last_exc = exc
-                if attempt < self._config.max_retries - 1:
+                if attempt < self._config.max_retries:
                     logger.debug(
                         "Connection error on attempt %d/%d, retrying: %s",
                         attempt + 1,
-                        self._config.max_retries,
+                        self._config.max_retries + 1,
                         exc,
                     )
                     time.sleep(self._compute_backoff(attempt))
@@ -149,7 +149,7 @@ def handle_request(self, request: httpx.Request) -> httpx.Response:
             if response.status_code not in self._config.retryable_status_codes:
                 return response
             self._notify_throttle(request)
-            if attempt < self._config.max_retries - 1:
+            if attempt < self._config.max_retries:
                 response.close()
                 retry_after = response.headers.get("retry-after")
                 if retry_after is not None:
@@ -201,16 +201,16 @@ def __init__(
 
     async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
         last_exc: httpx.TransportError | None = None
-        for attempt in range(self._config.max_retries):
+        for attempt in range(self._config.max_retries + 1):
             try:
                 response = await self._transport.handle_async_request(request)
             except httpx.TransportError as exc:
                 last_exc = exc
-                if attempt < self._config.max_retries - 1:
+                if attempt < self._config.max_retries:
                     logger.debug(
                         "Connection error on attempt %d/%d, retrying: %s",
                         attempt + 1,
-                        self._config.max_retries,
+                        self._config.max_retries + 1,
                         exc,
                     )
                     await asyncio.sleep(self._compute_backoff(attempt))
@@ -219,7 +219,7 @@ async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
             if response.status_code not in self._config.retryable_status_codes:
                 return response
             self._notify_throttle(request)
-            if attempt < self._config.max_retries - 1:
+            if attempt < self._config.max_retries:
                 await response.aclose()
                 retry_after = response.headers.get("retry-after")
                 if retry_after is not None:

tests/unit/_internal/test_retry_transport.py

@@ -33,7 +33,8 @@ def test_connection_error_is_retried_and_succeeds() -> None:
 
 
 def test_connection_error_exhausts_retries_and_raises() -> None:
-    rt, inner = _transport(max_retries=2)
+    # max_retries=1 → 2 total attempts (initial + 1 retry)
+    rt, inner = _transport(max_retries=1)
     inner.handle_request.side_effect = [
         httpx.RemoteProtocolError("peer closed connection"),
         httpx.RemoteProtocolError("peer closed connection"),
@@ -80,7 +81,8 @@ async def test_async_connection_error_is_retried_and_succeeds() -> None:
 
 @pytest.mark.asyncio
 async def test_async_connection_error_exhausts_retries_and_raises() -> None:
-    rt, inner = _async_transport(max_retries=2)
+    # max_retries=1 → 2 total attempts (initial + 1 retry)
+    rt, inner = _async_transport(max_retries=1)
     inner.handle_async_request.side_effect = [
         httpx.RemoteProtocolError("peer closed connection"),
         httpx.RemoteProtocolError("peer closed connection"),
@@ -158,7 +160,8 @@ def test_post_not_retried_on_400() -> None:
 
 
 def test_post_exhausts_retries_then_returns_503() -> None:
-    rt, inner = _transport(max_retries=3)
+    # max_retries=2 → 3 total attempts (initial + 2 retries)
+    rt, inner = _transport(max_retries=2)
     inner.handle_request.side_effect = [
         httpx.Response(503),
         httpx.Response(503),
@@ -170,7 +173,8 @@ def test_post_exhausts_retries_then_returns_503() -> None:
 
 
 def test_post_exhausts_retries_then_raises_transport_error() -> None:
-    rt, inner = _transport(max_retries=3)
+    # max_retries=2 → 3 total attempts (initial + 2 retries)
+    rt, inner = _transport(max_retries=2)
     inner.handle_request.side_effect = [
         httpx.ConnectError("fail"),
         httpx.ConnectError("fail"),

tests/unit/preview/test_async_indexes_exists.py

@@ -45,7 +45,7 @@ def indexes() -> AsyncPreviewIndexes:
     config = PineconeConfig(
         api_key="test-key",
         host=BASE_URL,
-        retry_config=RetryConfig(max_retries=1),
+        retry_config=RetryConfig(max_retries=0),
     )
     return AsyncPreviewIndexes(config=config)
 

tests/unit/preview/test_indexes_exists.py

@@ -44,7 +44,7 @@ def indexes() -> PreviewIndexes:
     config = PineconeConfig(
         api_key="test-key",
         host=BASE_URL,
-        retry_config=RetryConfig(max_retries=1),
+        retry_config=RetryConfig(max_retries=0),
     )
     return PreviewIndexes(config=config)
 

tests/unit/test_http_client.py

@@ -805,7 +805,8 @@ def test_on_throttle_called_on_429(self, monkeypatch: pytest.MonkeyPatch) -> Non
     def test_on_throttle_called_each_retry(self, monkeypatch: pytest.MonkeyPatch) -> None:
         monkeypatch.setattr("pinecone._internal.http_client.time.sleep", lambda _: None)
         mock_callback = MagicMock()
-        config = RetryConfig(max_retries=3, on_throttle=mock_callback)
+        # max_retries=2 → 3 total attempts (initial + 2 retries)
+        config = RetryConfig(max_retries=2, on_throttle=mock_callback)
         inner = _SequencedTransport([httpx.Response(429), httpx.Response(429), httpx.Response(429)])
         transport = _RetryTransport(transport=inner, retry_config=config)  # type: ignore[arg-type]
         request = httpx.Request("GET", "https://api.pinecone.io/indexes")

tests/unit/test_retry.py

@@ -204,10 +204,10 @@ def test_sync_exhausts_retries(self, mock_sleep: Any) -> None:
         )
         transport = _RetryTransport(
             transport=fake,  # type: ignore[arg-type]
-            retry_config=RetryConfig(max_retries=5, backoff_factor=2.0, max_wait=0.01),
+            # max_retries=4 → 5 total attempts (initial + 4 retries)
+            retry_config=RetryConfig(max_retries=4, backoff_factor=2.0, max_wait=0.01),
         )
         response = transport.handle_request(_make_request())
-        # max_retries=5 total, so 5 calls
         assert response.status_code == 503
         assert fake.call_count == 5
         assert mock_sleep.call_count == 4
@@ -327,8 +327,9 @@ def test_sync_backoff_capped(self, mock_sleep: Any, mock_uniform: Any) -> None:
         )
         transport = _RetryTransport(
             transport=fake,  # type: ignore[arg-type]
+            # max_retries=4 → 5 total attempts (initial + 4 retries) = 4 sleeps
             retry_config=RetryConfig(
-                max_retries=5,
+                max_retries=4,
                 backoff_factor=2.0,
                 max_wait=3.0,
             ),
@@ -516,7 +517,8 @@ def test_sync_closes_all_on_exhaustion(self, mock_sleep: Any) -> None:
         fake = _TrackingTransport(responses)
         transport = _RetryTransport(
             transport=fake,  # type: ignore[arg-type]
-            retry_config=RetryConfig(max_retries=3, backoff_factor=2.0, max_wait=0.01),
+            # max_retries=2 → 3 total attempts (initial + 2 retries)
+            retry_config=RetryConfig(max_retries=2, backoff_factor=2.0, max_wait=0.01),
         )
         result = transport.handle_request(_make_request())
         assert result.status_code == 500
@@ -597,10 +599,10 @@ async def test_async_exhausts_retries(self, mock_sleep: Any) -> None:
         )
         transport = _AsyncRetryTransport(
             transport=fake,  # type: ignore[arg-type]
-            retry_config=RetryConfig(max_retries=5, backoff_factor=2.0, max_wait=0.01),
+            # max_retries=4 → 5 total attempts (initial + 4 retries)
+            retry_config=RetryConfig(max_retries=4, backoff_factor=2.0, max_wait=0.01),
         )
         response = await transport.handle_async_request(_make_request())
-        # max_retries=5 total, so 5 calls
         assert response.status_code == 502
         assert fake.call_count == 5
         assert mock_sleep.call_count == 4
@@ -659,8 +661,9 @@ async def test_async_backoff_capped(self, mock_sleep: Any, mock_uniform: Any) ->
         )
         transport = _AsyncRetryTransport(
             transport=fake,  # type: ignore[arg-type]
+            # max_retries=4 → 5 total attempts (initial + 4 retries) = 4 sleeps
             retry_config=RetryConfig(
-                max_retries=5,
+                max_retries=4,
                 backoff_factor=2.0,
                 max_wait=3.0,
             ),
@@ -704,7 +707,8 @@ async def test_async_closes_all_on_exhaustion(self, mock_sleep: Any) -> None:
         fake = _TrackingAsyncTransport(responses)
         transport = _AsyncRetryTransport(
             transport=fake,  # type: ignore[arg-type]
-            retry_config=RetryConfig(max_retries=3, backoff_factor=2.0, max_wait=0.01),
+            # max_retries=2 → 3 total attempts (initial + 2 retries)
+            retry_config=RetryConfig(max_retries=2, backoff_factor=2.0, max_wait=0.01),
         )
         result = await transport.handle_async_request(_make_request())
         assert result.status_code == 503
@@ -781,14 +785,14 @@ def test_sync_client_retries_500_then_raises(self, mock_sleep: Any) -> None:
         )
         retry_transport = _RetryTransport(
             transport=fake,  # type: ignore[arg-type]
-            retry_config=RetryConfig(max_retries=3, backoff_factor=2.0, max_wait=0.01),
+            # max_retries=2 → 3 total attempts (initial + 2 retries)
+            retry_config=RetryConfig(max_retries=2, backoff_factor=2.0, max_wait=0.01),
         )
         client._client._transport = retry_transport  # type: ignore[assignment]
 
         with pytest.raises(ApiError) as exc_info:
             client.get("/indexes")
         assert exc_info.value.status_code == 500
-        # max_retries=3 total
         assert fake.call_count == 3
 
     @patch("pinecone._internal.http_client.time.sleep")

tests/unit/test_retry_config.py

@@ -104,7 +104,7 @@ def test_pinecone_config_custom_retry_config(self) -> None:
 class TestCustomRetryConfigSync:
     @patch("pinecone._internal.http_client.time.sleep")
     def test_custom_retry_config_max_retries(self, mock_sleep: Any) -> None:
-        """Custom RetryConfig with max_retries=2 only retries once."""
+        """Custom RetryConfig with max_retries=1 only retries once (2 total attempts)."""
         fake = _FakeTransport(
             [
                 httpx.Response(500, json={"message": "error"}),
@@ -114,7 +114,8 @@ def test_custom_retry_config_max_retries(self, mock_sleep: Any) -> None:
         )
         transport = _RetryTransport(
             transport=fake,  # type: ignore[arg-type]
-            retry_config=RetryConfig(max_retries=2, max_wait=0.01),
+            # max_retries=1 → 2 total attempts (initial + 1 retry)
+            retry_config=RetryConfig(max_retries=1, max_wait=0.01),
         )
         response = transport.handle_request(_get_request())
         assert response.status_code == 500
@@ -203,7 +204,7 @@ class TestCustomRetryConfigAsync:
     @patch("pinecone._internal.http_client.asyncio.sleep")
     @pytest.mark.asyncio
     async def test_custom_retry_config_max_retries(self, mock_sleep: Any) -> None:
-        """Custom RetryConfig with max_retries=2 only retries once."""
+        """Custom RetryConfig with max_retries=1 only retries once (2 total attempts)."""
         fake = _FakeAsyncTransport(
             [
                 httpx.Response(500, json={"message": "error"}),
@@ -213,7 +214,8 @@ async def test_custom_retry_config_max_retries(self, mock_sleep: Any) -> None:
         )
         transport = _AsyncRetryTransport(
             transport=fake,  # type: ignore[arg-type]
-            retry_config=RetryConfig(max_retries=2, max_wait=0.01),
+            # max_retries=1 → 2 total attempts (initial + 1 retry)
+            retry_config=RetryConfig(max_retries=1, max_wait=0.01),
         )
         response = await transport.handle_async_request(_get_request())
         assert response.status_code == 500