From 80272ed532d4b951a2eba8f164794f8c267bc7b5 Mon Sep 17 00:00:00 2001
From: Tyler Woods <tyler.woods66@gmail.com>
Date: Tue, 26 May 2026 20:53:49 +0000
Subject: [PATCH] fix: surface UniFi API error payloads

---
 tests/test_api_response_handling.py | 35 +++++++++++++++++++++++++++++
 unifi_controller_api/api_client.py  |  6 +++++
 2 files changed, 41 insertions(+)
 create mode 100644 tests/test_api_response_handling.py

diff --git a/tests/test_api_response_handling.py b/tests/test_api_response_handling.py
new file mode 100644
index 0000000..cad1405
--- /dev/null
+++ b/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": []})
diff --git a/unifi_controller_api/api_client.py b/unifi_controller_api/api_client.py
index f59c0f2..669d146 100644
--- a/unifi_controller_api/api_client.py
+++ b/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}"