fix: surface UniFi API error payloads

tests/test_api_response_handling.py

@@ -0,0 +1,35 @@
+from typing import Any, cast
+
+import pytest
+
+from unifi_controller_api import UnifiController
+from unifi_controller_api.exceptions import UnifiAPIError, UnifiDataError
+
+
+class FakeResponse:
+    def __init__(self, payload):
+        self._payload = payload
+
+    def json(self):
+        return self._payload
+
+
+def process(payload):
+    controller = UnifiController.__new__(UnifiController)
+    return controller._process_api_response(cast(Any, FakeResponse(payload)), "/api/test")
+
+
+def test_process_api_response_returns_data_items():
+    assert process({"meta": {"rc": "ok"}, "data": [{"name": "default"}]}) == [
+        {"name": "default"}
+    ]
+
+
+def test_process_api_response_rejects_missing_data_key():
+    with pytest.raises(UnifiDataError, match="Unexpected API response format"):
+        process({"meta": {"rc": "ok"}})
+
+
+def test_process_api_response_raises_api_error_for_unifi_error_payload():
+    with pytest.raises(UnifiAPIError, match="api.err.Invalid"):
+        process({"meta": {"rc": "error", "msg": "api.err.Invalid"}, "data": []})

unifi_controller_api/api_client.py

@@ -468,6 +468,12 @@ def _process_api_response(
 
         try:
             raw_data = response.json()
+            meta = raw_data.get("meta", {})
+            if meta.get("rc") == "error":
+                error_msg = meta.get("msg") or f"API request to {uri} failed"
+                logger.warning(f"UniFi API error for {uri}: {error_msg}")
+                raise UnifiAPIError(error_msg)
+
             raw_results = raw_data.get("data", [])
             if "data" not in raw_data:
                 error_msg = f"Unexpected API response format for {uri}"