feat: retry 502/503/504 with jittered backoff (#1)

* feat: retry 502/503/504 with jittered backoff Sync + async HTTP clients now retry up to 3 times on transient upstream
failures (502/503/504 or connect/read errors) with full-jitter exponential
backoff (500ms base → 4s cap). Shields SDK users from the ~3s cold-start
gap when the SharpAPI server restarts during deploys.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: drop Python 3.9 support Python 3.9 reached EOL 2025-10. The package declared 3.9 support but has
never actually worked on 3.9 — models.py uses `int | float` union syntax
which Pydantic evaluates at runtime and which fails on 3.9. Main-branch
CI has been red on 3.9 since the initial release.

Rather than adding a runtime dependency (eval_type_backport) or rewriting
all PEP 604 unions, drop 3.9 from the test matrix and bump floors in
pyproject.toml (requires-python, classifiers, ruff target-version,
pyright pythonVersion).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Mlaz-code

.github/workflows/test.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
       - uses: actions/checkout@v4

pyproject.toml

@@ -8,15 +8,14 @@ version = "0.2.1"
 description = "Official Python SDK for the SharpAPI real-time sports betting odds API"
 readme = "README.md"
 license = "MIT"
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 authors = [{ name = "SharpAPI", email = "support@sharpapi.io" }]
 keywords = ["sports-betting", "odds", "arbitrage", "ev", "api", "real-time", "pinnacle"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
@@ -43,7 +42,7 @@ Changelog = "https://github.com/Sharp-API/sharpapi-python/releases"
 packages = ["src/sharpapi"]
 
 [tool.ruff]
-target-version = "py39"
+target-version = "py310"
 line-length = 100
 
 [tool.ruff.lint]
@@ -54,7 +53,7 @@ asyncio_mode = "auto"
 testpaths = ["tests"]
 
 [tool.pyright]
-pythonVersion = "3.9"
+pythonVersion = "3.10"
 typeCheckingMode = "standard"
 venvPath = "."
 venv = ".venv"

src/sharpapi/_base.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import random
+
 import httpx
 
 from .exceptions import (
@@ -17,6 +19,24 @@
 DEFAULT_TIMEOUT = 30.0
 USER_AGENT = "sharpapi-python/0.2.0"
 
+RETRY_STATUSES = frozenset({502, 503, 504})
+RETRY_MAX_ATTEMPTS = 3
+RETRY_BASE_DELAY = 0.5
+RETRY_MAX_DELAY = 4.0
+
+
+def should_retry(response: httpx.Response | None, exc: Exception | None) -> bool:
+    """True for transient upstream failures worth retrying."""
+    if exc is not None:
+        return isinstance(exc, (httpx.ConnectError, httpx.ReadError, httpx.RemoteProtocolError))
+    return response is not None and response.status_code in RETRY_STATUSES
+
+
+def retry_delay(attempt: int) -> float:
+    """Exponential backoff with full jitter. attempt is 1-indexed."""
+    ceiling = min(RETRY_BASE_DELAY * (2 ** (attempt - 1)), RETRY_MAX_DELAY)
+    return random.uniform(0, ceiling)
+
 
 def parse_response(raw: dict, model_class: type) -> APIResponse:
     """Parse raw API JSON into a typed APIResponse."""

src/sharpapi/async_client.py

@@ -2,17 +2,21 @@
 
 from __future__ import annotations
 
+import asyncio
 from typing import Any, Optional, Union
 
 import httpx
 
 from ._base import (
     DEFAULT_BASE_URL,
     DEFAULT_TIMEOUT,
+    RETRY_MAX_ATTEMPTS,
     handle_errors,
     make_headers,
     parse_rate_limit,
     parse_response,
+    retry_delay,
+    should_retry,
 )
 from ._utils import _clean_params
 from .models import (
@@ -89,11 +93,26 @@ def rate_limit(self) -> RateLimitInfo:
         return self._last_rate_limit
 
     async def _request(self, method: str, path: str, params: dict | None = None, **kwargs) -> Any:
-        """Make an async API request and return parsed JSON."""
+        """Make an async API request and return parsed JSON. Retries 502/503/504 with jittered backoff."""
         if params:
             params = _clean_params(params)
 
-        response = await self._http.request(method, path, params=params, **kwargs)
+        response: httpx.Response | None = None
+        for attempt in range(1, RETRY_MAX_ATTEMPTS + 1):
+            exc: Exception | None = None
+            try:
+                response = await self._http.request(method, path, params=params, **kwargs)
+            except (httpx.ConnectError, httpx.ReadError, httpx.RemoteProtocolError) as e:
+                exc = e
+
+            if attempt < RETRY_MAX_ATTEMPTS and should_retry(response, exc):
+                await asyncio.sleep(retry_delay(attempt))
+                continue
+            if exc is not None:
+                raise exc
+            break
+
+        assert response is not None
         self._last_rate_limit = parse_rate_limit(response)
         handle_errors(response)
         return response.json()

src/sharpapi/client.py

@@ -2,17 +2,21 @@
 
 from __future__ import annotations
 
+import time
 from typing import Any, Optional, Union
 
 import httpx
 
 from ._base import (
     DEFAULT_BASE_URL,
     DEFAULT_TIMEOUT,
+    RETRY_MAX_ATTEMPTS,
     handle_errors,
     make_headers,
     parse_rate_limit,
     parse_response,
+    retry_delay,
+    should_retry,
 )
 from ._utils import _clean_params
 from .models import (
@@ -99,11 +103,26 @@ def rate_limit(self) -> RateLimitInfo:
         return self._last_rate_limit
 
     def _request(self, method: str, path: str, params: dict | None = None, **kwargs) -> Any:
-        """Make an API request and return parsed JSON."""
+        """Make an API request and return parsed JSON. Retries 502/503/504 with jittered backoff."""
         if params:
             params = _clean_params(params)
 
-        response = self._http.request(method, path, params=params, **kwargs)
+        response: httpx.Response | None = None
+        for attempt in range(1, RETRY_MAX_ATTEMPTS + 1):
+            exc: Exception | None = None
+            try:
+                response = self._http.request(method, path, params=params, **kwargs)
+            except (httpx.ConnectError, httpx.ReadError, httpx.RemoteProtocolError) as e:
+                exc = e
+
+            if attempt < RETRY_MAX_ATTEMPTS and should_retry(response, exc):
+                time.sleep(retry_delay(attempt))
+                continue
+            if exc is not None:
+                raise exc
+            break
+
+        assert response is not None
         self._last_rate_limit = parse_rate_limit(response)
         handle_errors(response)
         return response.json()