feat: add exponential backoff retry logic to HTTP requests

README.md

@@ -164,10 +164,41 @@ config = {
     "api_key": "your-api-key",              # Required: Your API key
     "api_url": "https://engine.lingo.dev",  # Optional: API endpoint
     "batch_size": 25,                       # Optional: Items per batch (1-250)
-    "ideal_batch_item_size": 250            # Optional: Target words per batch (1-2500)
+    "ideal_batch_item_size": 250,           # Optional: Target words per batch (1-2500)
+    "retry_max_attempts": 3,                # Optional: Max retry attempts (0-10, 0=disabled)
+    "retry_base_delay": 1.0,                # Optional: Base delay between retries (0.1-10.0s)
+    "retry_max_timeout": 60.0               # Optional: Total timeout for all retries (1-300s)
 }
 ```
 
+### 🔄 Retry Behavior
+
+The SDK automatically handles transient failures with intelligent exponential backoff:
+
+- **Retries**: 5xx server errors, 429 rate limits, and network timeouts
+- **No retries**: 4xx client errors (except 429)
+- **Exponential backoff**: `base_delay * (2^attempt) + jitter`
+- **Rate limiting**: Respects `Retry-After` headers from 429 responses
+- **Timeout protection**: Stops retrying if total time would exceed `retry_max_timeout`
+
+```python
+# Custom retry configuration
+from lingodotdev import EngineConfig
+
+config = EngineConfig(
+    api_key="your-api-key",
+    retry_max_attempts=5,      # More aggressive retrying
+    retry_base_delay=0.5,      # Faster initial retry
+    retry_max_timeout=30.0     # Shorter total timeout
+)
+
+async with LingoDotDevEngine(config) as engine:
+    result = await engine.localize_text("Hello", {"target_locale": "es"})
+
+# Disable retries completely
+config = EngineConfig(api_key="your-api-key", retry_max_attempts=0)
+```
+
 ## 🎛️ Method Parameters
 
 ### Translation Parameters

src/lingodotdev/engine.py

@@ -5,6 +5,8 @@
 # mypy: disable-error-code=unreachable
 
 import asyncio
+import logging
+import random
 from typing import Any, Callable, Dict, List, Optional
 from urllib.parse import urljoin
 
@@ -20,6 +22,9 @@ class EngineConfig(BaseModel):
     api_url: str = "https://engine.lingo.dev"
     batch_size: int = Field(default=25, ge=1, le=250)
     ideal_batch_item_size: int = Field(default=250, ge=1, le=2500)
+    retry_max_attempts: int = Field(default=3, ge=0, le=10)
+    retry_base_delay: float = Field(default=1.0, ge=0.1, le=10.0)
+    retry_max_timeout: float = Field(default=60.0, ge=1.0, le=300.0)
 
     @validator("api_url")
     @classmethod
@@ -80,6 +85,121 @@ async def close(self):
         if self._client and not self._client.is_closed:
             await self._client.aclose()
 
+    def _should_retry_response(self, response: httpx.Response) -> bool:
+        """
+        Determine if a response should be retried.
+
+        Args:
+            response: The HTTP response to evaluate
+
+        Returns:
+            True if the response indicates a retryable error, False otherwise
+        """
+        # Retry on server errors (5xx) and rate limiting (429)
+        return response.status_code >= 500 or response.status_code == 429
+
+    def _calculate_retry_delay(self, attempt: int, response: Optional[httpx.Response]) -> float:
+        """
+        Calculate delay for next retry attempt using exponential backoff with jitter.
+
+        Args:
+            attempt: The current attempt number (0-based)
+            response: The HTTP response (if available) to check for Retry-After header
+
+        Returns:
+            Delay in seconds before next retry attempt
+        """
+        # Base exponential backoff: base_delay * (2 ^ attempt)
+        base_delay = self.config.retry_base_delay * (2 ** attempt)
+
+        # Handle 429 Retry-After header
+        if response and response.status_code == 429:
+            retry_after = response.headers.get('retry-after')
+            if retry_after:
+                try:
+                    retry_after_seconds = float(retry_after)
+                    base_delay = max(base_delay, retry_after_seconds)
+                except ValueError:
+                    # Invalid retry-after header, use exponential backoff
+                    pass
+
+        # Add jitter (0-10% of calculated delay) to prevent thundering herd
+        jitter = random.uniform(0, 0.1 * base_delay)
+        return base_delay + jitter
+
+    async def _make_request_with_retry(
+        self, url: str, request_data: Dict[str, Any]
+    ) -> httpx.Response:
+        """
+        Make HTTP request with exponential backoff retry logic.
+
+        Args:
+            url: The URL to make the request to
+            request_data: The JSON data to send in the request
+
+        Returns:
+            The HTTP response from the successful request
+
+        Raises:
+            RuntimeError: When all retry attempts are exhausted or timeout exceeded
+        """
+        await self._ensure_client()
+        assert self._client is not None  # Type guard for mypy
+
+        import time
+        start_time = time.time()
+        last_exception = None
+        logger = logging.getLogger(__name__)
+        timeout_exceeded = False
+
+        for attempt in range(self.config.retry_max_attempts + 1):
+            try:
+                response = await self._client.post(url, json=request_data)
+
+                # Check if response should be retried
+                if self._should_retry_response(response) and attempt < self.config.retry_max_attempts:
+                    delay = self._calculate_retry_delay(attempt, response)
+
+                    # Check if delay would exceed total timeout
+                    elapsed_time = time.time() - start_time
+                    if elapsed_time + delay > self.config.retry_max_timeout:
+                        logger.debug(f"Retry timeout would be exceeded, stopping retries after {elapsed_time:.1f}s")
+                        timeout_exceeded = True
+                        break
+
+                    logger.debug(f"Request failed with status {response.status_code}, retrying in {delay:.1f}s (attempt {attempt + 1}/{self.config.retry_max_attempts + 1})")
+                    await asyncio.sleep(delay)
+                    continue
+
+                if attempt > 0:
+                    logger.debug(f"Request succeeded after {attempt + 1} attempts")
+                return response
+
+            except httpx.RequestError as e:
+                last_exception = e
+                if attempt < self.config.retry_max_attempts:
+                    delay = self._calculate_retry_delay(attempt, None)
+
+                    # Check if delay would exceed total timeout
+                    elapsed_time = time.time() - start_time
+                    if elapsed_time + delay > self.config.retry_max_timeout:
+                        logger.debug(f"Retry timeout would be exceeded, stopping retries after {elapsed_time:.1f}s")
+                        timeout_exceeded = True
+                        break
+
+                    logger.debug(f"Request failed with {type(e).__name__}: {e}, retrying in {delay:.1f}s (attempt {attempt + 1}/{self.config.retry_max_attempts + 1})")
+                    await asyncio.sleep(delay)
+                    continue
+                break
+
+        # All retries exhausted or timeout exceeded
+        total_attempts = attempt + 1
+        elapsed_time = time.time() - start_time
+        if timeout_exceeded:
+            raise RuntimeError(f"Request failed after {elapsed_time:.1f}s (timeout exceeded): {last_exception}")
+        else:
+            raise RuntimeError(f"Request failed after {total_attempts} attempts: {last_exception}")
+
     async def _localize_raw(
         self,
         payload: Dict[str, Any],
@@ -181,7 +301,7 @@ async def _localize_chunk(
             request_data["reference"] = payload["reference"]
 
         try:
-            response = await self._client.post(url, json=request_data)
+            response = await self._make_request_with_retry(url, request_data)
 
             if not response.is_success:
                 if 500 <= response.status_code < 600:
@@ -423,7 +543,7 @@ async def recognize_locale(self, text: str) -> str:
         url = urljoin(self.config.api_url, "/recognize")
 
         try:
-            response = await self._client.post(url, json={"text": text})
+            response = await self._make_request_with_retry(url, {"text": text})
 
             if not response.is_success:
                 if 500 <= response.status_code < 600:
@@ -453,7 +573,7 @@ async def whoami(self) -> Optional[Dict[str, str]]:
         url = urljoin(self.config.api_url, "/whoami")
 
         try:
-            response = await self._client.post(url)
+            response = await self._make_request_with_retry(url, {})
 
             if response.is_success:
                 payload = response.json()