fix: add error field to ContentStatus for failed content retrievals

exa_py/api.py

@@ -1160,13 +1160,22 @@ def close(self) -> None:
 T = TypeVar("T")
 
 
+@dataclass
+class ContentStatusError:
+    """Error details for a failed content retrieval."""
+
+    http_status_code: Optional[int] = None
+    tag: Optional[str] = None
+
+
 @dataclass
 class ContentStatus:
     """A class representing the status of a content retrieval operation."""
 
     id: str
     status: str
-    source: str
+    source: Optional[str] = None
+    error: Optional[ContentStatusError] = None
 
 
 @dataclass
@@ -1671,11 +1680,19 @@ def get_contents(self, urls: Union[str, List[str], List[_Result]], **kwargs):
         cost_dollars = parse_cost_dollars(data.get("costDollars"))
         statuses = []
         for status in data.get("statuses", []):
+            error_data = status.get("error")
+            error = None
+            if error_data is not None:
+                error = ContentStatusError(
+                    http_status_code=error_data.get("httpStatusCode"),
+                    tag=error_data.get("tag"),
+                )
             statuses.append(
                 ContentStatus(
                     id=status.get("id"),
                     status=status.get("status"),
                     source=status.get("source"),
+                    error=error,
                 )
             )
         results = []
@@ -2625,11 +2642,19 @@ async def get_contents(self, urls: Union[str, List[str], List[_Result]], **kwarg
         cost_dollars = parse_cost_dollars(data.get("costDollars"))
         statuses = []
         for status in data.get("statuses", []):
+            error_data = status.get("error")
+            error = None
+            if error_data is not None:
+                error = ContentStatusError(
+                    http_status_code=error_data.get("httpStatusCode"),
+                    tag=error_data.get("tag"),
+                )
             statuses.append(
                 ContentStatus(
                     id=status.get("id"),
                     status=status.get("status"),
                     source=status.get("source"),
+                    error=error,
                 )
             )
         results = []

tests/unit/test_search_api.py

@@ -22,6 +22,27 @@ def test_contentstatus_parsing_offline():
     payload_status = {"id": "u", "status": "success", "source": "cached"}
     cs = exa_api.ContentStatus(**payload_status)
     assert cs.id == "u" and cs.status == "success" and cs.source == "cached"
+    assert cs.error is None
+
+
+def test_contentstatus_with_error_parsing_offline():
+    payload_status = {
+        "id": "u",
+        "status": "error",
+        "error": {"httpStatusCode": 404, "tag": "NOT_FOUND"},
+    }
+    cs = exa_api.ContentStatus(
+        id=payload_status["id"],
+        status=payload_status["status"],
+        error=exa_api.ContentStatusError(
+            http_status_code=payload_status["error"]["httpStatusCode"],
+            tag=payload_status["error"]["tag"],
+        ),
+    )
+    assert cs.id == "u" and cs.status == "error"
+    assert cs.error is not None
+    assert cs.error.http_status_code == 404
+    assert cs.error.tag == "NOT_FOUND"
 
 
 def test_answerresponse_accepts_dict():