python-sendparcel-inpost 0.1.2__py3-none-any.whl → 0.3.0__py3-none-any.whl

{python_sendparcel_inpost-0.1.2.dist-info → python_sendparcel_inpost-0.3.0.dist-info}/METADATA

@@ -1,9 +1,14 @@
 Metadata-Version: 2.4
 Name: python-sendparcel-inpost
-Version: 0.1.2
+Version: 0.3.0
 Summary: InPost ShipX provider for python-sendparcel.
+Project-URL: Homepage, https://github.com/python-sendparcel/python-sendparcel-inpost
+Project-URL: Repository, https://github.com/python-sendparcel/python-sendparcel-inpost
+Project-URL: Changelog, https://github.com/python-sendparcel/python-sendparcel-inpost/blob/main/CHANGELOG.md
+Project-URL: Issue Tracker, https://github.com/python-sendparcel/python-sendparcel-inpost/issues
 Author-email: Dominik Kozaczko <dominik@kozaczko.info>
 License: MIT
+License-File: LICENSE
 Keywords: inpost,parcel,sendparcel,shipping,shipx
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
@@ -17,13 +22,14 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: anyio>=4.0
 Requires-Dist: httpx>=0.27.0
-Requires-Dist: python-sendparcel>=0.1.1
+Requires-Dist: python-sendparcel>=0.3.0
 Provides-Extra: dev
 Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: respx>=0.22.0; extra == 'dev'
 Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Requires-Dist: ty>=0.0.1a11; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # python-sendparcel-inpost

python_sendparcel_inpost-0.3.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+sendparcel_inpost/__init__.py,sha256=Tkz5IeAveOLj_1CtR8xKfuon2URY9rst-qsKY66yLqI,548
+sendparcel_inpost/circuit_breaker.py,sha256=RZ6Sry63Jh9y7OdUCdXACxOIIfkgyiGggFG7h34DPCA,4939
+sendparcel_inpost/client.py,sha256=jftpFhvmcQDmpkAm8Bac0tqW5w4IxoC1frB9nso-Mqs,14920
+sendparcel_inpost/exceptions.py,sha256=E79mErjpni41_U9A2Ql2Cw4yAKd82cpguRPwNiamg2Y,2142
+sendparcel_inpost/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sendparcel_inpost/rate_limiter.py,sha256=sct5bYofsdKGLcGrCUXWeciyGIq_yr332kP7oLpTCZE,1870
+sendparcel_inpost/status_mapping.py,sha256=9UDU8XFCWKfKXPyWTV9E_dzgExdZjgZrBkcWUYj2smI,2782
+sendparcel_inpost/types.py,sha256=Pu-OJpC6te4_gY6PLv-Ag0o2IoulYytdr9t0FGf4GIA,1426
+sendparcel_inpost/providers/__init__.py,sha256=akn431q6mekenZV5Y4wjCh2UkLSi2s51umBHZ37orJg,336
+sendparcel_inpost/providers/base.py,sha256=7uQ8e0K0NPHOQ1-JM9XGyc5OzWd3OKUO_Goqm65sL0M,13952
+sendparcel_inpost/providers/courier.py,sha256=gdjZmoBlLTQa73x_JRameJQYCg2F9WhBwt2S-_0r2UU,2592
+sendparcel_inpost/providers/locker.py,sha256=mzn5WvnCi7lLWPoWW7NaHMty-vb4gzFSpgb9ucCHV0o,2867
+python_sendparcel_inpost-0.3.0.dist-info/METADATA,sha256=IRnCMaIs50L-d62gMvbzSd848VITd2JHIeo8_TUqPMM,3446
+python_sendparcel_inpost-0.3.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+python_sendparcel_inpost-0.3.0.dist-info/entry_points.txt,sha256=XuQdmE0LIuIc3TvGPWnYjoB14zXCEof6Q8h1tMp2arE,170
+python_sendparcel_inpost-0.3.0.dist-info/licenses/LICENSE,sha256=IZXSBOjgGvChgayLmtTnU40iE7hsrrU3WVEYKx0sywY,1075
+python_sendparcel_inpost-0.3.0.dist-info/RECORD,,

{python_sendparcel_inpost-0.1.2.dist-info → python_sendparcel_inpost-0.3.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.29.0
+Generator: hatchling 1.30.1
 Root-Is-Purelib: true
 Tag: py3-none-any

python_sendparcel_inpost-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,10 @@
+
+MIT License
+
+Copyright (c) 2025, Dominik Kozaczko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

sendparcel_inpost/__init__.py

@@ -1,14 +1,18 @@
 """InPost ShipX provider for python-sendparcel."""
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"
 
 from sendparcel_inpost.client import ShipXClient
+from sendparcel_inpost.exceptions import CircuitBreakerError
+from sendparcel_inpost.providers.base import aclose_transports
 from sendparcel_inpost.providers.courier import InPostCourierProvider
 from sendparcel_inpost.providers.locker import InPostLockerProvider
 
 __all__ = [
+    "CircuitBreakerError",
     "InPostCourierProvider",
     "InPostLockerProvider",
     "ShipXClient",
     "__version__",
+    "aclose_transports",
 ]

sendparcel_inpost/circuit_breaker.py

@@ -0,0 +1,155 @@
+"""Circuit breaker and metrics for external API resilience."""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ShipXMetrics:
+    """Collects metrics for a single ShipXClient instance.
+
+    Thread-safe. Use ``snapshot()`` to get a point-in-time view.
+    """
+
+    _lock: threading.Lock = field(default_factory=threading.Lock)
+    _request_count: int = 0
+    _error_count: int = 0
+    _circuit_trip_count: int = 0
+    _retry_count: int = 0
+    _total_latency_ms: float = 0.0
+    _max_latency_ms: float = 0.0
+    _last_error: str | None = None
+    _last_error_at: float | None = None
+    _circuit_state: str = "closed"
+
+    @property
+    def circuit_state(self) -> str:
+        with self._lock:
+            return self._circuit_state
+
+    def set_circuit_state(self, state: str) -> None:
+        with self._lock:
+            self._circuit_state = state
+
+    def record_request(
+        self,
+        latency_ms: float,
+        success: bool,
+        error: str | None = None,
+    ) -> None:
+        with self._lock:
+            self._request_count += 1
+            self._total_latency_ms += latency_ms
+            if latency_ms > self._max_latency_ms:
+                self._max_latency_ms = latency_ms
+            if not success:
+                self._error_count += 1
+                self._last_error = error
+                self._last_error_at = time.time()
+
+    def record_circuit_trip(self) -> None:
+        with self._lock:
+            self._circuit_trip_count += 1
+
+    def record_retry(self) -> None:
+        with self._lock:
+            self._retry_count += 1
+
+    def snapshot(self) -> dict[str, Any]:
+        """Return a point-in-time copy of all metrics."""
+        with self._lock:
+            avg_latency = (
+                self._total_latency_ms / self._request_count
+                if self._request_count > 0
+                else 0.0
+            )
+            return {
+                "request_count": self._request_count,
+                "error_count": self._error_count,
+                "retry_count": self._retry_count,
+                "circuit_trip_count": self._circuit_trip_count,
+                "circuit_state": self._circuit_state,
+                "avg_latency_ms": round(avg_latency, 2),
+                "max_latency_ms": round(self._max_latency_ms, 2),
+                "last_error": self._last_error,
+                "last_error_at": self._last_error_at,
+            }
+
+
+class _CircuitBreaker:
+    """Simple circuit breaker for the ShipX API.
+
+    States:
+    - CLOSED: normal operation, requests pass through
+    - OPEN: circuit tripped, requests fail fast
+    - HALF_OPEN: one probe request allowed after cooldown
+
+    Transitions:
+    - CLOSED → OPEN: after `threshold` consecutive failures
+    - OPEN → HALF_OPEN: after `cooldown` seconds
+    - HALF_OPEN → CLOSED: probe request succeeds
+    - HALF_OPEN → OPEN: probe request fails
+    """
+
+    class State:
+        CLOSED = "closed"
+        OPEN = "open"
+        HALF_OPEN = "half_open"
+
+    def __init__(
+        self,
+        threshold: int = 5,
+        cooldown: float = 30.0,
+    ) -> None:
+        self._threshold = threshold
+        self._cooldown = cooldown
+        self._state = self.State.CLOSED
+        self._failures = 0
+        self._opened_at: float | None = None
+
+    @property
+    def state(self) -> str:
+        """Current circuit state, transitioning OPEN → HALF_OPEN on cooldown."""
+        if self._state == self.State.OPEN and self._opened_at is not None:
+            elapsed = time.monotonic() - self._opened_at
+            if elapsed >= self._cooldown:
+                self._state = self.State.HALF_OPEN
+        return self._state
+
+    @property
+    def failures(self) -> int:
+        return self._failures
+
+    @property
+    def cooldown_remaining(self) -> float:
+        if self._state != self.State.OPEN or self._opened_at is None:
+            return 0.0
+        elapsed = time.monotonic() - self._opened_at
+        return max(0.0, self._cooldown - elapsed)
+
+    def allow_request(self) -> bool:
+        """Check if a request should be allowed through."""
+        current = self.state  # triggers OPEN → HALF_OPEN transition
+        return current != self.State.OPEN
+
+    def record_success(self) -> None:
+        """Record a successful request."""
+        self._failures = 0
+        self._state = self.State.CLOSED
+        self._opened_at = None
+
+    def record_failure(self) -> None:
+        """Record a failed request."""
+        self._failures += 1
+        if self.state == self.State.HALF_OPEN:
+            # Probe failed — reopen circuit
+            self._state = self.State.OPEN
+            self._opened_at = time.monotonic()
+        elif self._failures >= self._threshold:
+            # Threshold reached — open circuit
+            self._state = self.State.OPEN
+            self._opened_at = time.monotonic()

sendparcel_inpost/client.py

@@ -1,20 +1,37 @@
 """ShipX API async HTTP client."""
 
+from __future__ import annotations
+
+import logging
+import time
 from types import TracebackType
-from typing import Any
+from typing import Any, cast
 
+import anyio
 import httpx
 
+from sendparcel_inpost.circuit_breaker import ShipXMetrics, _CircuitBreaker
 from sendparcel_inpost.exceptions import (
+    CircuitBreakerError,
     ShipXAPIError,
     ShipXAuthenticationError,
     ShipXValidationError,
 )
+from sendparcel_inpost.rate_limiter import _TokenBucket
+
+logger = logging.getLogger(__name__)
+
 
 PRODUCTION_BASE_URL = "https://api-shipx-pl.easypack24.net"
 SANDBOX_BASE_URL = "https://sandbox-api-shipx-pl.easypack24.net"
 
 DEFAULT_TIMEOUT = 30.0
+DEFAULT_RATE_LIMIT = 10.0  # requests per second
+DEFAULT_BURST = 5  # maximum burst size
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_RETRY_BASE_DELAY = 1.0  # seconds
+DEFAULT_CIRCUIT_THRESHOLD = 5  # consecutive failures to open circuit
+DEFAULT_CIRCUIT_COOLDOWN = 30.0  # seconds before allowing probe request
 
 
 class ShipXClient:
@@ -22,10 +39,18 @@ class ShipXClient:
 
     Can be used standalone (independent of sendparcel providers).
 
-    Usage::
+    Usage as context manager::
 
         async with ShipXClient(token="...", organization_id=123) as client:
             result = await client.create_shipment(payload={...})
+
+    Usage as long-lived client (shared across multiple calls)::
+
+        client = ShipXClient(token="...", organization_id=123)
+        try:
+            result = await client.create_shipment(payload={...})
+        finally:
+            await client.close()
     """
 
     def __init__(
@@ -36,6 +61,12 @@ class ShipXClient:
         sandbox: bool = False,
         base_url: str | None = None,
         timeout: float = DEFAULT_TIMEOUT,
+        rate_limit: float = DEFAULT_RATE_LIMIT,
+        burst: int = DEFAULT_BURST,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        retry_base_delay: float = DEFAULT_RETRY_BASE_DELAY,
+        circuit_threshold: int = DEFAULT_CIRCUIT_THRESHOLD,
+        circuit_cooldown: float = DEFAULT_CIRCUIT_COOLDOWN,
     ) -> None:
         if base_url is not None:
             self.base_url = base_url
@@ -45,6 +76,13 @@ class ShipXClient:
             self.base_url = PRODUCTION_BASE_URL
         self.organization_id = organization_id
         self.timeout = timeout
+        self._max_retries = max_retries
+        self._retry_base_delay = retry_base_delay
+        self._circuit = _CircuitBreaker(
+            threshold=circuit_threshold,
+            cooldown=circuit_cooldown,
+        )
+        self._metrics = ShipXMetrics()
         self._http = httpx.AsyncClient(
             base_url=self.base_url,
             headers={
@@ -53,8 +91,9 @@ class ShipXClient:
             },
             timeout=timeout,
         )
+        self._rate_limiter = _TokenBucket(rate=rate_limit, burst=burst)
 
-    async def __aenter__(self) -> "ShipXClient":
+    async def __aenter__(self) -> ShipXClient:
         return self
 
     async def __aexit__(
@@ -69,26 +108,187 @@ class ShipXClient:
         """Close the underlying HTTP client."""
         await self._http.aclose()
 
+    @property
+    def metrics(self) -> ShipXMetrics:
+        """Return the metrics collector for this client."""
+        return self._metrics
+
+    async def _retry(
+        self,
+        coro: Any,
+        *,
+        idempotent: bool = True,
+    ) -> Any:
+        """Execute a coroutine with exponential backoff retry
+        and circuit breaker.
+
+        The circuit breaker fails fast when the API is consistently down,
+        preventing requests from queuing up and waiting 30s each.
+
+        Args:
+            coro: The coroutine to execute.
+            idempotent: If True, retry on all transient errors.
+                If False, only retry on server errors (5xx).
+                POST operations should use idempotent=False unless
+                an idempotency key is provided.
+        """
+        start = time.monotonic()
+        retries = 0
+        op_name = getattr(coro, "__qualname__", repr(coro))
+
+        # Check circuit breaker before attempting any work
+        if not self._circuit.allow_request():
+            self._metrics.record_circuit_trip()
+            self._metrics.set_circuit_state(self._circuit.state)
+            raise CircuitBreakerError(
+                "Circuit breaker is open — InPost API is unavailable",
+                failures=self._circuit.failures,
+                cooldown_remaining=self._circuit.cooldown_remaining,
+            )
+
+        last_exc: Exception | None = None
+        for attempt in range(1 + self._max_retries):
+            try:
+                result = await coro()
+                self._circuit.record_success()
+                self._metrics.set_circuit_state(self._circuit.state)
+                latency_ms = (time.monotonic() - start) * 1000
+                self._metrics.record_request(latency_ms, success=True)
+                return result
+            except (
+                ShipXAuthenticationError,
+                ShipXValidationError,
+            ) as exc:
+                # These are client errors — do not retry, do not trip circuit.
+                latency_ms = (time.monotonic() - start) * 1000
+                self._metrics.record_request(
+                    latency_ms,
+                    success=False,
+                    error=f"{type(exc).__name__}: {exc}",
+                )
+                raise
+            except (
+                httpx.ConnectError,
+                httpx.ConnectTimeout,
+                httpx.ReadTimeout,
+                httpx.WriteTimeout,
+                httpx.RemoteProtocolError,
+                httpx.PoolTimeout,
+            ) as exc:
+                last_exc = exc
+                self._circuit.record_failure()
+                self._metrics.set_circuit_state(self._circuit.state)
+                if attempt < self._max_retries:
+                    retries += 1
+                    self._metrics.record_retry()
+                    delay = self._retry_base_delay * (2**attempt)
+                    logger.warning(
+                        "Retry %d/%d for %s after %.1fs: %s",
+                        attempt + 1,
+                        self._max_retries,
+                        op_name,
+                        delay,
+                        exc,
+                    )
+                    await anyio.sleep(delay)
+                else:
+                    latency_ms = (time.monotonic() - start) * 1000
+                    self._metrics.record_request(
+                        latency_ms,
+                        success=False,
+                        error=f"{type(exc).__name__}: {exc}",
+                    )
+                    raise
+            except ShipXAPIError as exc:
+                # 429: the request was rejected before processing, so it
+                # is safe to retry regardless of idempotency. Rate
+                # limiting is not a service failure — don't trip the
+                # circuit. 5xx: retry only idempotent operations.
+                rate_limited = exc.status_code == 429
+                retryable = rate_limited or (
+                    exc.status_code >= 500 and idempotent
+                )
+                if retryable:
+                    last_exc = exc
+                    if not rate_limited:
+                        self._circuit.record_failure()
+                        self._metrics.set_circuit_state(self._circuit.state)
+                    if attempt < self._max_retries:
+                        retries += 1
+                        self._metrics.record_retry()
+                        delay = self._retry_base_delay * (2**attempt)
+                        if rate_limited and exc.retry_after is not None:
+                            delay = exc.retry_after
+                        logger.warning(
+                            "Retry %d/%d for %s after %.1fs: HTTP %d %s",
+                            attempt + 1,
+                            self._max_retries,
+                            op_name,
+                            delay,
+                            exc.status_code,
+                            exc.detail,
+                        )
+                        await anyio.sleep(delay)
+                    else:
+                        latency_ms = (time.monotonic() - start) * 1000
+                        self._metrics.record_request(
+                            latency_ms,
+                            success=False,
+                            error=f"HTTP {exc.status_code} {exc.detail}",
+                        )
+                        raise
+                else:
+                    latency_ms = (time.monotonic() - start) * 1000
+                    self._metrics.record_request(
+                        latency_ms,
+                        success=False,
+                        error=f"HTTP {exc.status_code} {exc.detail}",
+                    )
+                    raise
+
+        assert last_exc is not None
+        latency_ms = (time.monotonic() - start) * 1000
+        self._metrics.record_request(
+            latency_ms,
+            success=False,
+            error=f"{type(last_exc).__name__}: {last_exc}",
+        )
+        raise last_exc
+
+    async def _rate_limit(self) -> None:
+        """Apply rate limiting before making an API call."""
+        await self._rate_limiter.acquire()
+
     async def create_shipment(self, payload: dict[str, Any]) -> dict[str, Any]:
         """Create a shipment via simplified flow.
 
         POST /v1/organizations/{org_id}/shipments
         """
-        url = f"/v1/organizations/{self.organization_id}/shipments"
-        response = await self._http.post(url, json=payload)
-        self._raise_for_status(response)
-        result: dict[str, Any] = response.json()
-        return result
+
+        async def _do() -> dict[str, Any]:
+            await self._rate_limit()
+            url = f"/v1/organizations/{self.organization_id}/shipments"
+            response = await self._http.post(url, json=payload)
+            self._raise_for_status(response)
+            result: dict[str, Any] = cast(dict[str, Any], response.json())
+            return result
+
+        return cast(dict[str, Any], await self._retry(_do, idempotent=False))
 
     async def get_shipment(self, shipment_id: int) -> dict[str, Any]:
         """Fetch shipment details.
 
         GET /v1/shipments/{shipment_id}
         """
-        response = await self._http.get(f"/v1/shipments/{shipment_id}")
-        self._raise_for_status(response)
-        result: dict[str, Any] = response.json()
-        return result
+
+        async def _do() -> dict[str, Any]:
+            await self._rate_limit()
+            response = await self._http.get(f"/v1/shipments/{shipment_id}")
+            self._raise_for_status(response)
+            result: dict[str, Any] = cast(dict[str, Any], response.json())
+            return result
+
+        return cast(dict[str, Any], await self._retry(_do, idempotent=True))
 
     async def get_label(
         self,
@@ -101,53 +301,88 @@ class ShipXClient:
 
         GET /v1/shipments/{shipment_id}/label?format=...&type=...
         """
-        response = await self._http.get(
-            f"/v1/shipments/{shipment_id}/label",
-            params={"format": label_format, "type": label_type},
-        )
-        self._raise_for_status(response)
-        return response.content
+
+        async def _do() -> bytes:
+            await self._rate_limit()
+            response = await self._http.get(
+                f"/v1/shipments/{shipment_id}/label",
+                params={"format": label_format, "type": label_type},
+            )
+            self._raise_for_status(response)
+            content = response.content
+            assert isinstance(content, bytes)
+            return content
+
+        return cast(bytes, await self._retry(_do, idempotent=True))
 
     async def cancel_shipment(self, shipment_id: int) -> None:
         """Cancel a shipment.
 
         DELETE /v1/shipments/{shipment_id}
         """
-        response = await self._http.delete(f"/v1/shipments/{shipment_id}")
-        self._raise_for_status(response)
+
+        async def _do() -> None:
+            await self._rate_limit()
+            response = await self._http.delete(f"/v1/shipments/{shipment_id}")
+            self._raise_for_status(response)
+
+        await self._retry(_do, idempotent=True)
 
     async def get_tracking(self, tracking_number: str) -> dict[str, Any]:
         """Fetch public tracking data (no auth required).
 
         GET /v1/tracking/{tracking_number}
         """
-        response = await self._http.get(f"/v1/tracking/{tracking_number}")
-        self._raise_for_status(response)
-        result: dict[str, Any] = response.json()
-        return result
+
+        async def _do() -> dict[str, Any]:
+            await self._rate_limit()
+            response = await self._http.get(f"/v1/tracking/{tracking_number}")
+            self._raise_for_status(response)
+            result: dict[str, Any] = cast(dict[str, Any], response.json())
+            return result
+
+        return cast(dict[str, Any], await self._retry(_do, idempotent=True))
 
     async def get_statuses(self, lang: str = "pl") -> list[dict[str, Any]]:
         """Fetch list of all ShipX statuses.
 
         GET /v1/statuses
         """
-        response = await self._http.get(
-            "/v1/statuses",
-            params={"lang": lang},
+
+        async def _do() -> list[dict[str, Any]]:
+            await self._rate_limit()
+            response = await self._http.get(
+                "/v1/statuses",
+                params={"lang": lang},
+            )
+            self._raise_for_status(response)
+            result: list[dict[str, Any]] = cast(
+                list[dict[str, Any]], response.json()
+            )
+            return result
+
+        return cast(
+            list[dict[str, Any]], await self._retry(_do, idempotent=True)
         )
-        self._raise_for_status(response)
-        result: list[dict[str, Any]] = response.json()
-        return result
 
     async def get_services(self) -> list[dict[str, Any]]:
         """Fetch list of all ShipX services.
 
         GET /v1/services
         """
-        response = await self._http.get("/v1/services")
-        self._raise_for_status(response)
-        result: list[dict[str, Any]] = response.json()
-        return result
+
+        async def _do() -> list[dict[str, Any]]:
+            await self._rate_limit()
+            response = await self._http.get("/v1/services")
+            self._raise_for_status(response)
+            result: list[dict[str, Any]] = cast(
+                list[dict[str, Any]], response.json()
+            )
+            return result
+
+        return cast(
+            list[dict[str, Any]], await self._retry(_do, idempotent=True)
+        )
 
     def _raise_for_status(self, response: httpx.Response) -> None:
         """Raise ShipXAPIError subclasses for non-2xx responses."""
@@ -174,4 +409,17 @@ class ShipXClient:
             status_code=status_code,
             detail=str(detail),
             errors=errors,
+            retry_after=_parse_retry_after(response),
         )
+
+
+def _parse_retry_after(response: httpx.Response) -> float | None:
+    """Parse the Retry-After header as delay seconds, if present."""
+    raw = response.headers.get("Retry-After")
+    if raw is None:
+        return None
+    try:
+        return max(0.0, float(raw))
+    except ValueError:
+        # HTTP-date form — not worth parsing; fall back to backoff.
+        return None