feat: normalize API error contracts

README.md

@@ -158,12 +158,27 @@ except RateLimitError as error:
 except TimeoutError:
     print("Retry once, then check https://status.oilpriceapi.com.")
 except OilPriceAPIError as error:
+    # Safe support context: do not log your API key or request headers.
+    if error.request_id:
+        print("Support request ID:", error.request_id)
     if error.status_code in (402, 403):
-        print("Review dataset access for this account.")
+        print(
+            "Review dataset access for this account.",
+            error.required_plan,
+            error.required_feature,
+            error.remediation_url,
+        )
     else:
         raise
 ```
 
+All non-2xx responses share the same `OilPriceAPIError` attributes, including
+`status_code`, `code`, `request_id`, plan/feature recovery fields, retry
+metadata, sanitized response `headers`, `raw_body`, and `raw_text`. Canonical
+nested and legacy flat API error envelopes are normalized into that contract.
+Transport failures use `NetworkError`; timeouts remain the more specific
+`TimeoutError`.
+
 Executable recovery examples cover 401, 403, 429, and timeout responses under
 [`examples/snippets/`](examples/snippets/). Empty or malformed successful
 responses should stop analysis rather than inventing a price, unit, currency,

docs/index.md

@@ -182,21 +182,29 @@ client = OilPriceAPI(
 ### Error Handling
 
 ```python
-from oilpriceapi.exceptions import (
-    OilPriceAPIError,
-    RateLimitError,
-    DataNotFoundError
-)
-
-try:
-    price = client.prices.get("BRENT_CRUDE_USD")
-except RateLimitError as e:
-    print(f"Rate limited. Resets in {e.seconds_until_reset}s")
-except DataNotFoundError:
-    print("Commodity not found")
-except OilPriceAPIError as e:
-    print(f"API error: {e}")
-```
+from oilpriceapi import (
+    DataNotFoundError,
+    OilPriceAPIError,
+    RateLimitError,
+)
+
+try:
+    price = client.prices.get("BRENT_CRUDE_USD")
+except RateLimitError as error:
+    print(f"Rate limited. Resets in {error.seconds_until_reset}s")
+except DataNotFoundError:
+    print("Commodity not found")
+except OilPriceAPIError as error:
+    if error.request_id:
+        print("Support request ID:", error.request_id)
+    if error.remediation_url:
+        print("Recovery:", error.remediation_url)
+    print(f"API error: {error}")
+```
+
+Every non-2xx response uses this shared typed contract. `status_code`, `code`,
+plan or feature requirements, retry metadata, sanitized response headers, and
+raw diagnostics remain available without exposing the configured API key.
 
 ## 💰 Pricing & Plans
 

oilpriceapi/__init__.py

@@ -15,9 +15,13 @@
 from oilpriceapi.client import OilPriceAPI
 from oilpriceapi.exceptions import (
     AuthenticationError,
+    BadRequestError,
     ConfigurationError,
     DataNotFoundError,
+    NetworkError,
     OilPriceAPIError,
+    PaymentRequiredError,
+    PermissionDeniedError,
     RateLimitError,
     ServerError,
     TimeoutError,
@@ -49,11 +53,15 @@
     "OilPriceAPI",
     "AsyncOilPriceAPI",
     "OilPriceAPIError",
+    "BadRequestError",
     "AuthenticationError",
+    "PaymentRequiredError",
+    "PermissionDeniedError",
     "RateLimitError",
     "DataNotFoundError",
     "ServerError",
     "ValidationError",
+    "NetworkError",
     "TimeoutError",
     "ConfigurationError",
     "DieselPrice",