feat: parse structured 429 responses for descriptive rate limit errors

RateLimitError now includes tier, detail dict, and human-readable
message from the server (e.g. "Daily query limit reached (100/100).
Contact hello@datons.com for Professional tier.") instead of the
generic "Rate limit exceeded."

Author: jsulopzs

src/datons/client.py

@@ -98,7 +98,18 @@ def _request(
             raise AuthenticationError()
         if response.status_code == 429:
             retry_after = response.headers.get("Retry-After")
-            raise RateLimitError(int(retry_after) if retry_after else None)
+            # Parse structured error body from server
+            try:
+                body = response.json()
+                detail = body.get("detail", body)
+            except Exception:
+                detail = None
+            tier = detail.get("tier") if isinstance(detail, dict) else None
+            raise RateLimitError(
+                int(retry_after) if retry_after else None,
+                tier=tier,
+                detail=detail,
+            )
         if response.status_code >= 400:
             detail = response.text[:500]
             raise QueryError(response.status_code, detail)

src/datons/exceptions.py

@@ -21,11 +21,34 @@ def __init__(self, status_code: int, detail: str = ""):
 
 
 class RateLimitError(DatonsError):
-    """Rate limit exceeded."""
-
-    def __init__(self, retry_after: int | None = None):
+    """Rate limit exceeded.
+
+    Attributes:
+        retry_after: Seconds until the limit resets.
+        tier: Current API key tier (e.g. 'explorer', 'professional').
+        detail: Full error detail from the server.
+    """
+
+    def __init__(
+        self,
+        retry_after: int | None = None,
+        *,
+        tier: str | None = None,
+        detail: dict | str | None = None,
+    ):
         self.retry_after = retry_after
-        msg = "Rate limit exceeded."
-        if retry_after:
-            msg += f" Retry after {retry_after}s."
+        self.tier = tier
+        self.detail = detail
+
+        # Build a human-readable message from the server response
+        if isinstance(detail, dict):
+            msg = detail.get("error", "Rate limit exceeded.")
+            upgrade = detail.get("upgrade")
+            if upgrade:
+                msg += f" {upgrade}"
+        else:
+            msg = "Rate limit exceeded."
+            if retry_after:
+                msg += f" Retry after {retry_after}s."
+
         super().__init__(msg)