fix: address error contract review

Author: karlwaldman

docs/index.md

@@ -182,7 +182,7 @@ client = OilPriceAPI(
 ### Error Handling
 
 ```python
-from oilpriceapi.exceptions import (
+from oilpriceapi import (
     DataNotFoundError,
     OilPriceAPIError,
     RateLimitError,

oilpriceapi/client.py

@@ -401,6 +401,12 @@ def request_with_headers(
                 elif response.status_code >= 500:
                     if self._retry_strategy.should_retry(attempt, response.status_code):
                         wait_time = self._retry_strategy.calculate_wait_time(attempt)
+                        self._retry_strategy.log_retry(
+                            attempt,
+                            f"Server error {response.status_code}",
+                            wait_time,
+                            is_async=False,
+                        )
                         time.sleep(wait_time)
                         continue
                 raise error_from_response(
@@ -416,6 +422,9 @@ def request_with_headers(
                 )
                 if self._retry_strategy.should_retry_on_exception(attempt):
                     wait_time = self._retry_strategy.calculate_wait_time(attempt)
+                    self._retry_strategy.log_retry(
+                        attempt, "Request timeout", wait_time, is_async=False
+                    )
                     time.sleep(wait_time)
                     continue
                 raise last_exception
@@ -426,6 +435,12 @@ def request_with_headers(
                 )
                 if self._retry_strategy.should_retry_on_exception(attempt):
                     wait_time = self._retry_strategy.calculate_wait_time(attempt)
+                    self._retry_strategy.log_retry(
+                        attempt,
+                        f"Request error: {error.__class__.__name__}",
+                        wait_time,
+                        is_async=False,
+                    )
                     time.sleep(wait_time)
                     continue
                 raise last_exception

oilpriceapi/exceptions.py

@@ -3,6 +3,8 @@
 from datetime import datetime
 from typing import Any, Dict, Iterable, List, Mapping, Optional, Tuple
 
+import httpx
+
 _SENSITIVE_HEADERS = {
     "authorization",
     "proxy-authorization",
@@ -360,9 +362,10 @@ def __init__(
         self,
         message: str = "Request timed out",
         timeout: Optional[float] = None,
+        cause_type: str = "TimeoutException",
         **kwargs: Any,
     ):
-        super().__init__(message, cause_type="TimeoutException", **kwargs)
+        super().__init__(message, cause_type=cause_type, **kwargs)
         self.timeout = timeout
 
     def __str__(self) -> str:
@@ -509,9 +512,13 @@ def error_from_exception(
 ) -> OilPriceAPIError:
     """Normalize transport failures while redacting the configured API key."""
     secrets = [api_key] if api_key else []
-    if "Timeout" in error.__class__.__name__:
-        return TimeoutError(timeout=timeout)
     message = _redact_text(str(error), secrets)
+    if isinstance(error, httpx.TimeoutException):
+        return TimeoutError(
+            message=f"Request timed out: {message}" if message else "Request timed out",
+            timeout=timeout,
+            cause_type=error.__class__.__name__,
+        )
     return NetworkError(
         message=f"Request failed: {message}",
         cause_type=error.__class__.__name__,

tests/unit/test_error_contract.py

@@ -80,6 +80,9 @@ def test_canonical_nested_error_preserves_recovery_contract():
     assert "authorization" not in error.headers
     assert "secret-test-key" not in error.raw_text
     assert "secret-test-key" not in repr(error.raw_body)
+    assert error.retryable is False
+    assert error.is_client_error is True
+    assert error.is_server_error is False
 
 
 def test_legacy_flat_error_and_rate_limit_headers_are_normalized():
@@ -148,35 +151,42 @@ def test_malformed_non_json_body_is_preserved_without_losing_type():
     assert error.raw_body == "<html>upstream unavailable</html>"
     assert error.raw_text == "<html>upstream unavailable</html>"
     assert error.headers["content-type"] == "text/html"
+    assert error.retryable is True
+    assert error.is_server_error is True
 
 
 def test_sync_client_normalizes_timeout_and_network_failures():
     timeout_request = httpx.Request("GET", "https://api.oilpriceapi.com/v1/prices/latest")
-    client = OilPriceAPI(api_key="secret-test-key", max_retries=1)
-
-    with patch.object(
-        client._client,
-        "request",
-        side_effect=httpx.ReadTimeout("timed out", request=timeout_request),
-    ):
-        with pytest.raises(TimeoutError) as timeout:
-            client.request("GET", "/v1/prices/latest")
-
-    assert timeout.value.timeout == client.timeout
-
-    with patch.object(
-        client._client,
-        "request",
-        side_effect=httpx.ConnectError(
-            "connection failed for secret-test-key",
-            request=timeout_request,
-        ),
-    ):
-        with pytest.raises(NetworkError) as network:
-            client.request("GET", "/v1/prices/latest")
-
-    assert "secret-test-key" not in str(network.value)
-    assert network.value.cause_type == "ConnectError"
+    with OilPriceAPI(api_key="secret-test-key", max_retries=1) as client:
+        with patch.object(
+            client._client,
+            "request",
+            side_effect=httpx.ReadTimeout(
+                "timed out for secret-test-key",
+                request=timeout_request,
+            ),
+        ):
+            with pytest.raises(TimeoutError) as timeout:
+                client.request("GET", "/v1/prices/latest")
+
+        assert timeout.value.timeout == client.timeout
+        assert timeout.value.cause_type == "ReadTimeout"
+        assert "secret-test-key" not in str(timeout.value)
+
+        with patch.object(
+            client._client,
+            "request",
+            side_effect=httpx.ConnectError(
+                "connection failed for secret-test-key",
+                request=timeout_request,
+            ),
+        ):
+            with pytest.raises(NetworkError) as network:
+                client.request("GET", "/v1/prices/latest")
+
+        assert "secret-test-key" not in str(network.value)
+        assert network.value.cause_type == "ConnectError"
+        assert network.value.retryable is True
 
 
 @pytest.mark.asyncio