retry only retryable failures, honour retry-after

Author: Polliog

CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.5] - 2026-06-11
+
+### Changed
+
+- **Permanent client errors (4xx except 408/429) are no longer retried** (sync and async): the batch is dropped after the first attempt instead of burning the full retry budget
+- A `Retry-After` header on `429`/`503` responses now overrides the computed backoff delay
+
 ## [0.9.4] - 2026-06-11
 
 ### Added

logtide_sdk/_retry.py

@@ -0,0 +1,52 @@
+"""Failure classification for the transport retry loops (spec 002 §6).
+
+Retryable: network errors, 408, 429, 5xx. Permanent client errors (other
+4xx) must be dropped after the first attempt. A Retry-After header
+(delta-seconds form) overrides the computed backoff delay.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = ["classify_failure"]
+
+
+def _status_and_headers(exc: Exception) -> tuple[int | None, Any]:
+    # requests.HTTPError carries .response with .status_code/.headers
+    response = getattr(exc, "response", None)
+    if response is not None:
+        status = getattr(response, "status_code", None)
+        if status is not None:
+            return status, getattr(response, "headers", None)
+    # aiohttp.ClientResponseError carries .status/.headers directly
+    status = getattr(exc, "status", None)
+    if isinstance(status, int):
+        return status, getattr(exc, "headers", None)
+    return None, None
+
+
+def classify_failure(exc: Exception) -> tuple[bool, float | None]:
+    """Return ``(retryable, retry_after_seconds)`` for a send failure."""
+    status, headers = _status_and_headers(exc)
+
+    if status is None:
+        return True, None  # network/timeout errors: retry with backoff
+
+    retryable = status in (408, 429) or status >= 500
+
+    retry_after: float | None = None
+    if headers is not None:
+        try:
+            raw = headers.get("Retry-After")
+        except AttributeError:
+            raw = None
+        if raw is not None:
+            try:
+                seconds = float(raw)
+                if seconds >= 0:
+                    retry_after = seconds
+            except (TypeError, ValueError):
+                pass
+
+    return retryable, retry_after

logtide_sdk/_version.py

@@ -4,5 +4,5 @@
 import it without circular imports. Bump together with ``pyproject.toml``.
 """
 
-VERSION = "0.9.4"
+VERSION = "0.9.5"
 SDK_NAME = "logtide-python"

logtide_sdk/async_client.py

@@ -21,6 +21,7 @@
 from logtide_sdk.enums import CircuitState, LogLevel
 from logtide_sdk.exceptions import CircuitBreakerOpenError
 from logtide_sdk.json_encoder import logtide_json_dumps
+from logtide_sdk._retry import classify_failure
 from logtide_sdk._version import SDK_NAME, VERSION
 from logtide_sdk.scope import get_current_scope
 from logtide_sdk.tracecontext import generate_trace_id
@@ -530,11 +531,22 @@ async def _send_logs_with_retry(self, logs: list[LogEntry]) -> None:
                 attempt += 1
                 self._circuit_breaker.record_failure()
 
+                retryable, retry_after = classify_failure(e)
+
                 with self._metrics_lock:
                     self._metrics.errors += 1
-                    if attempt <= self.options.max_retries:
+                    if retryable and attempt <= self.options.max_retries:
                         self._metrics.retries += 1
 
+                # Permanent client errors (4xx except 408/429) will not become
+                # valid by retrying: drop the batch after the first attempt.
+                if not retryable:
+                    if self.options.debug:
+                        print(f"[LogTide] Non-retryable error, dropping batch: {e}")
+                    with self._metrics_lock:
+                        self._metrics.logs_dropped += len(logs)
+                    break
+
                 if attempt > self.options.max_retries:
                     if self.options.debug:
                         print(f"[LogTide] Failed to send logs after {attempt} attempts: {e}")
@@ -545,7 +557,8 @@ async def _send_logs_with_retry(self, logs: list[LogEntry]) -> None:
                 if self.options.debug:
                     print(f"[LogTide] Retry {attempt}/{self.options.max_retries} in {delay}s")
 
-                await asyncio.sleep(delay)
+                # A server-provided Retry-After overrides the computed backoff
+                await asyncio.sleep(retry_after if retry_after is not None else delay)
                 delay *= 2
 
         if self._circuit_breaker.state == CircuitState.OPEN and state_before != CircuitState.OPEN:

logtide_sdk/client.py

@@ -17,6 +17,7 @@
 from logtide_sdk.enums import CircuitState, LogLevel
 from logtide_sdk.exceptions import CircuitBreakerOpenError
 from logtide_sdk.json_encoder import logtide_json_dumps
+from logtide_sdk._retry import classify_failure
 from logtide_sdk._version import SDK_NAME, VERSION
 from logtide_sdk.scope import get_current_scope
 from logtide_sdk.tracecontext import generate_trace_id
@@ -712,11 +713,22 @@ def _send_logs_with_retry(self, log_entries: list[LogEntry]) -> None:
                 attempt += 1
                 self._circuit_breaker.record_failure()
 
+                retryable, retry_after = classify_failure(e)
+
                 with self._metrics_lock:
                     self._metrics.errors += 1
-                    if attempt <= self.options.max_retries:
+                    if retryable and attempt <= self.options.max_retries:
                         self._metrics.retries += 1
 
+                # Permanent client errors (4xx except 408/429) will not become
+                # valid by retrying: drop the batch after the first attempt.
+                if not retryable:
+                    if self.options.debug:
+                        print(f"[LogTide] Non-retryable error, dropping batch: {e}")
+                    with self._metrics_lock:
+                        self._metrics.logs_dropped += len(log_entries)
+                    break
+
                 if attempt > self.options.max_retries:
                     if self.options.debug:
                         print(f"[LogTide] Failed to send logs after {attempt} attempts: {e}")
@@ -734,7 +746,8 @@ def _send_logs_with_retry(self, log_entries: list[LogEntry]) -> None:
                         self._metrics.logs_dropped += len(log_entries)
                     break
 
-                time.sleep(delay)
+                # A server-provided Retry-After overrides the computed backoff
+                time.sleep(retry_after if retry_after is not None else delay)
                 delay *= 2
 
         # Only count a trip when the circuit *transitions* to OPEN during this call,

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "logtide-sdk"
-version = "0.9.4"
+version = "0.9.5"
 description = "Official Python SDK for LogTide - Self-hosted log management with async client, logging integration, batching, retry, circuit breaker, and middleware"
 readme = "README.md"
 license = { text = "MIT" }

tests/test_retry_policy.py

@@ -0,0 +1,149 @@
+"""Retry policy per spec 002 §6 (conformance C07/C08/C09).
+
+Retryable: network errors, 408, 429, 5xx. Permanent client errors (other
+4xx) are dropped after the first attempt. A Retry-After header overrides the
+computed backoff delay.
+"""
+
+from unittest.mock import Mock
+
+import pytest
+import requests
+
+from logtide_sdk import ClientOptions, LogTideClient
+from logtide_sdk.models import LogEntry
+from logtide_sdk.enums import LogLevel
+
+
+def http_error(status: int, headers: dict | None = None) -> requests.HTTPError:
+    response = Mock(spec=requests.Response)
+    response.status_code = status
+    response.headers = headers or {}
+    return requests.HTTPError(f"HTTP {status}", response=response)
+
+
+@pytest.fixture
+def client():
+    c = LogTideClient(
+        ClientOptions(
+            api_url="http://localhost:8080",
+            api_key="lp_k",
+            service="svc",
+            retry_delay_ms=1,
+        )
+    )
+    yield c
+    c._closed = True
+
+
+def entry() -> LogEntry:
+    return LogEntry(service="svc", level=LogLevel.INFO, message="m")
+
+
+def test_no_retry_on_permanent_4xx(client, mocker):
+    send = mocker.patch.object(client, "_send_logs", side_effect=http_error(400))
+    sleep = mocker.patch("logtide_sdk.client.time.sleep")
+
+    client._send_logs_with_retry([entry()])
+
+    assert send.call_count == 1, "400 must not be retried"
+    sleep.assert_not_called()
+    metrics = client.get_metrics()
+    assert metrics.logs_dropped == 1
+    assert metrics.retries == 0
+
+
+def test_no_retry_on_401(client, mocker):
+    send = mocker.patch.object(client, "_send_logs", side_effect=http_error(401))
+    client._send_logs_with_retry([entry()])
+    assert send.call_count == 1
+
+
+def test_retries_on_5xx_then_succeeds(client, mocker):
+    send = mocker.patch.object(
+        client, "_send_logs", side_effect=[http_error(500), None]
+    )
+    mocker.patch("logtide_sdk.client.time.sleep")
+
+    client._send_logs_with_retry([entry()])
+
+    assert send.call_count == 2
+    metrics = client.get_metrics()
+    assert metrics.logs_sent == 1
+    assert metrics.retries == 1
+
+
+def test_retries_on_408_and_429(client, mocker):
+    send = mocker.patch.object(
+        client, "_send_logs", side_effect=[http_error(408), http_error(429), None]
+    )
+    mocker.patch("logtide_sdk.client.time.sleep")
+    client._send_logs_with_retry([entry()])
+    assert send.call_count == 3
+
+
+def test_retries_on_network_error(client, mocker):
+    send = mocker.patch.object(
+        client,
+        "_send_logs",
+        side_effect=[requests.ConnectionError("refused"), None],
+    )
+    mocker.patch("logtide_sdk.client.time.sleep")
+    client._send_logs_with_retry([entry()])
+    assert send.call_count == 2
+
+
+def test_retry_after_overrides_backoff(client, mocker):
+    mocker.patch.object(
+        client,
+        "_send_logs",
+        side_effect=[http_error(429, {"Retry-After": "7"}), None],
+    )
+    sleep = mocker.patch("logtide_sdk.client.time.sleep")
+
+    client._send_logs_with_retry([entry()])
+
+    sleep.assert_called_once_with(7.0)
+
+
+@pytest.mark.asyncio
+async def test_async_no_retry_on_permanent_4xx(mocker):
+    import aiohttp
+
+    from logtide_sdk.async_client import AsyncLogTideClient
+
+    client = AsyncLogTideClient(
+        ClientOptions(api_url="http://localhost:8080", api_key="lp_k", service="svc")
+    )
+    try:
+        error = aiohttp.ClientResponseError(
+            request_info=Mock(), history=(), status=403, headers={}
+        )
+        send = mocker.patch.object(client, "_send_logs", side_effect=error)
+        await client._send_logs_with_retry([entry()])
+        assert send.call_count == 1, "403 must not be retried"
+    finally:
+        client._closed = True
+
+
+@pytest.mark.asyncio
+async def test_async_retry_after_overrides_backoff(mocker):
+    import aiohttp
+
+    from logtide_sdk.async_client import AsyncLogTideClient
+
+    client = AsyncLogTideClient(
+        ClientOptions(
+            api_url="http://localhost:8080", api_key="lp_k", service="svc", retry_delay_ms=1
+        )
+    )
+    try:
+        error = aiohttp.ClientResponseError(
+            request_info=Mock(), history=(), status=429, headers={"Retry-After": "5"}
+        )
+        mocker.patch.object(client, "_send_logs", side_effect=[error, None])
+        sleep = mocker.patch("logtide_sdk.async_client.asyncio.sleep")
+        await client._send_logs_with_retry([entry()])
+        sleep.assert_called_once_with(5.0)
+    finally:
+        client._closed = True