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()

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()

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()

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()

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()

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()

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()

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()