fix(retry): add 408 to retryable status codes, align docs, add POST coverage tests

## Purpose

Legacy AGENTS.md incorrectly documented that only GET/HEAD requests are retried.
The implementation has always retried all HTTP methods (no method filter exists in
_RetryTransport). Additionally, 408 Request Timeout was missing from the default
retryable status codes despite being a well-known retry-safe transient signal
(RFC 7231 §6.5.7). Test coverage for POST-specific retry scenarios was absent,
creating a regression risk.

## Solution

- Added `408` to `RetryConfig.retryable_status_codes` default in `_internal/config.py`.
- Corrected AGENTS.md retry-behavior paragraph to document that all HTTP methods
  are retried, with rationale (Pinecone data-plane writes are idempotent by ID).
- Added 10 new targeted test cases in `tests/unit/_internal/test_retry_transport.py`:
  POST upsert/query retry on ConnectError and 503, 408 retry, 429+Retry-After,
  non-retryable 400, exhaustion returning 503 or raising ConnectError; plus async
  mirrors for upsert/query/408.
- Created `tests/unit/_internal/test_http_client.py` with fast-path POST retry
  guard: verifies that `HTTPClient.post()` still goes through `_RetryTransport`
  even though the fast path calls `_client._transport.handle_request()` directly.
- Updated `tests/unit/test_retry_config.py` to reflect the new 408 default.

## Follow-ups

gRPC retry policy broadening (ResourceExhausted, Aborted) is covered by P-0228.

Author: jhamon

AGENTS.md

@@ -283,7 +283,7 @@ except PineconeError as e:
     print(e)  # Validation, timeout, or connection error
 ```
 
-**Retry behavior:** Only GET/HEAD requests are automatically retried (on 500/502/503/504). POST operations (upsert, query, search) are not retried — implement your own retry logic for transient errors. Configure via `RetryConfig`.
+**Retry behavior:** All HTTP methods (GET, HEAD, POST, PUT, PATCH, DELETE) are automatically retried on transient failures: connection errors (`httpx.TransportError`), 408 Request Timeout, 429 Too Many Requests (honoring `Retry-After`), and 5xx (500, 502, 503, 504). Pinecone's data-plane writes are idempotent at the server (upsert overwrites by ID, delete-by-ID is idempotent, update-by-ID is idempotent), so retrying upsert/query/fetch/delete/update on transient errors is safe. Backoff is floored full jitter: `uniform(0.1 * base, base)` where `base = min(backoff_factor**attempt, max_wait)`. Configure via `RetryConfig`.
 
 ## Response Objects
 

pinecone/_internal/config.py

@@ -80,14 +80,14 @@ class RetryConfig:
         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
-            ``{429, 500, 502, 503, 504}``.
+            ``{408, 429, 500, 502, 503, 504}``.
     """
 
     max_retries: int = 3
     backoff_factor: float = 2.0
     max_wait: float = 60.0
     retryable_status_codes: frozenset[int] = field(
-        default_factory=lambda: frozenset({429, 500, 502, 503, 504})
+        default_factory=lambda: frozenset({408, 429, 500, 502, 503, 504})
     )
 
 

tests/unit/_internal/test_http_client.py

@@ -0,0 +1,68 @@
+"""Tests for HTTPClient.post fast-path retry behavior."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+import httpx
+import pytest
+
+from pinecone._internal.config import PineconeConfig, RetryConfig
+from pinecone._internal.http_client import HTTPClient
+
+
+def _make_client(max_retries: int = 2) -> HTTPClient:
+    retry_config = RetryConfig(max_retries=max_retries, backoff_factor=0.0, max_wait=0.0)
+    config = PineconeConfig(
+        api_key="test-key-1234",
+        host="https://test.example.com",
+        retry_config=retry_config,
+    )
+    return HTTPClient(config, "2025-10")
+
+
+def test_fast_path_post_retried_on_connect_error() -> None:
+    """Fast-path POST bypasses Client.send() but still goes through _RetryTransport."""
+    client = _make_client(max_retries=2)
+
+    mock_inner = MagicMock(spec=httpx.BaseTransport)
+    mock_inner.handle_request.side_effect = [
+        httpx.ConnectError("connection refused"),
+        httpx.Response(200, content=b"{}"),
+    ]
+    # Swap the inner transport inside _RetryTransport so retry logic wraps the mock.
+    client._client._transport._transport = mock_inner  # type: ignore[attr-defined]
+
+    result = client.post("/some/path", json={"foo": "bar"})
+    assert result.status_code == 200
+    assert mock_inner.handle_request.call_count == 2
+
+
+def test_fast_path_post_succeeds_on_first_try() -> None:
+    client = _make_client()
+
+    mock_inner = MagicMock(spec=httpx.BaseTransport)
+    mock_inner.handle_request.return_value = httpx.Response(200, content=b"{}")
+    client._client._transport._transport = mock_inner  # type: ignore[attr-defined]
+
+    result = client.post("/vectors/upsert", json={"vectors": []})
+    assert result.status_code == 200
+    assert mock_inner.handle_request.call_count == 1
+
+
+@pytest.mark.asyncio
+async def test_fast_path_uses_retry_transport_not_client_send() -> None:
+    """Regression guard: if _RetryTransport is bypassed, retry count would be 1."""
+    client = _make_client(max_retries=3)
+
+    mock_inner = MagicMock(spec=httpx.BaseTransport)
+    mock_inner.handle_request.side_effect = [
+        httpx.ConnectError("reset by peer"),
+        httpx.ConnectError("reset by peer"),
+        httpx.Response(200, content=b"{}"),
+    ]
+    client._client._transport._transport = mock_inner  # type: ignore[attr-defined]
+
+    result = client.post("/query", json={"vector": [0.1, 0.2]})
+    assert result.status_code == 200
+    assert mock_inner.handle_request.call_count == 3

tests/unit/_internal/test_retry_transport.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from unittest.mock import AsyncMock, MagicMock
+from unittest.mock import AsyncMock, MagicMock, patch
 
 import httpx
 import pytest
@@ -104,3 +104,113 @@ async def test_async_non_retryable_status_returns_immediately() -> None:
     result = await rt.handle_async_request(_req())
     assert result.status_code == 400
     assert inner.handle_async_request.call_count == 1
+
+
+# --- POST-specific named tests (sync) ---
+
+
+def test_post_upsert_retried_on_transport_error() -> None:
+    rt, inner = _transport(max_retries=3)
+    inner.handle_request.side_effect = [
+        httpx.ConnectError("boom"),
+        httpx.Response(200),
+    ]
+    result = rt.handle_request(httpx.Request("POST", "https://example.com/vectors/upsert"))
+    assert result.status_code == 200
+    assert inner.handle_request.call_count == 2
+
+
+def test_post_query_retried_on_503() -> None:
+    rt, inner = _transport(max_retries=3)
+    inner.handle_request.side_effect = [httpx.Response(503), httpx.Response(200)]
+    result = rt.handle_request(httpx.Request("POST", "https://example.com/query"))
+    assert result.status_code == 200
+    assert inner.handle_request.call_count == 2
+
+
+def test_post_retried_on_408() -> None:
+    rt, inner = _transport(max_retries=3)
+    inner.handle_request.side_effect = [httpx.Response(408), httpx.Response(200)]
+    result = rt.handle_request(httpx.Request("POST", "https://example.com/query"))
+    assert result.status_code == 200
+    assert inner.handle_request.call_count == 2
+
+
+def test_post_retried_on_429_with_retry_after() -> None:
+    rt, inner = _transport(max_retries=3)
+    inner.handle_request.side_effect = [
+        httpx.Response(429, headers={"Retry-After": "0"}),
+        httpx.Response(200),
+    ]
+    with patch("pinecone._internal.http_client.time.sleep") as mock_sleep:
+        result = rt.handle_request(httpx.Request("POST", "https://example.com/query"))
+    assert result.status_code == 200
+    assert inner.handle_request.call_count == 2
+    mock_sleep.assert_called_once_with(0.0)
+
+
+def test_post_not_retried_on_400() -> None:
+    rt, inner = _transport(max_retries=3)
+    inner.handle_request.return_value = httpx.Response(400)
+    result = rt.handle_request(httpx.Request("POST", "https://example.com/query"))
+    assert result.status_code == 400
+    assert inner.handle_request.call_count == 1
+
+
+def test_post_exhausts_retries_then_returns_503() -> None:
+    rt, inner = _transport(max_retries=3)
+    inner.handle_request.side_effect = [
+        httpx.Response(503),
+        httpx.Response(503),
+        httpx.Response(503),
+    ]
+    result = rt.handle_request(httpx.Request("POST", "https://example.com/query"))
+    assert result.status_code == 503
+    assert inner.handle_request.call_count == 3
+
+
+def test_post_exhausts_retries_then_raises_transport_error() -> None:
+    rt, inner = _transport(max_retries=3)
+    inner.handle_request.side_effect = [
+        httpx.ConnectError("fail"),
+        httpx.ConnectError("fail"),
+        httpx.ConnectError("fail"),
+    ]
+    with pytest.raises(httpx.ConnectError):
+        rt.handle_request(httpx.Request("POST", "https://example.com/query"))
+    assert inner.handle_request.call_count == 3
+
+
+# --- POST-specific named tests (async) ---
+
+
+@pytest.mark.asyncio
+async def test_async_post_upsert_retried_on_transport_error() -> None:
+    rt, inner = _async_transport(max_retries=3)
+    inner.handle_async_request.side_effect = [
+        httpx.ConnectError("boom"),
+        httpx.Response(200),
+    ]
+    result = await rt.handle_async_request(
+        httpx.Request("POST", "https://example.com/vectors/upsert")
+    )
+    assert result.status_code == 200
+    assert inner.handle_async_request.call_count == 2
+
+
+@pytest.mark.asyncio
+async def test_async_post_query_retried_on_503() -> None:
+    rt, inner = _async_transport(max_retries=3)
+    inner.handle_async_request.side_effect = [httpx.Response(503), httpx.Response(200)]
+    result = await rt.handle_async_request(httpx.Request("POST", "https://example.com/query"))
+    assert result.status_code == 200
+    assert inner.handle_async_request.call_count == 2
+
+
+@pytest.mark.asyncio
+async def test_async_post_retried_on_408() -> None:
+    rt, inner = _async_transport(max_retries=3)
+    inner.handle_async_request.side_effect = [httpx.Response(408), httpx.Response(200)]
+    result = await rt.handle_async_request(httpx.Request("POST", "https://example.com/query"))
+    assert result.status_code == 200
+    assert inner.handle_async_request.call_count == 2

tests/unit/test_retry_config.py

@@ -74,7 +74,7 @@ def test_default_retry_config(self) -> None:
         assert cfg.max_retries == 3
         assert cfg.backoff_factor == 2.0
         assert cfg.max_wait == 60.0
-        assert cfg.retryable_status_codes == frozenset({429, 500, 502, 503, 504})
+        assert cfg.retryable_status_codes == frozenset({408, 429, 500, 502, 503, 504})
 
     def test_retry_config_has_no_retryable_methods(self) -> None:
         cfg = RetryConfig()