Enhance AxmeAuthError messages for status codes 401 and 403

axme_sdk/client.py

@@ -1936,8 +1936,16 @@ def _raise_http_error(self, response: httpx.Response) -> None:
             "retry_after": retry_after,
         }
         status_code = response.status_code
-        if status_code in (401, 403):
-            raise AxmeAuthError(status_code, message, **kwargs)
+        if status_code == 401:
+            raise AxmeAuthError(
+                status_code,
+                f"API key invalid - check AXME_API_KEY or run `axme login`. Server: {message}"
+                **kwargs)
+        if status_code == 403:
+            raise AxmeAuthError(
+                status_code,
+                f"Access denied. Check permissions. Server: {message}"
+                **kwargs)
         if status_code in (400, 409, 413, 422):
             raise AxmeValidationError(status_code, message, **kwargs)
         if status_code == 429:

tests/test_client.py

@@ -1886,7 +1886,6 @@ def handler(request: httpx.Request) -> httpx.Response:
     result = next(client.listen("org/ws/bot"))
     assert result["intent_id"] == "x1"
 
-
 def test_listen_raises_auth_error_on_401() -> None:
     from axme.exceptions import AxmeAuthError
 
@@ -1896,3 +1895,14 @@ def handler(request: httpx.Request) -> httpx.Response:
     client = _client(handler)
     with pytest.raises(AxmeAuthError):
         list(client.listen("org/ws/bot"))
+
+def test_401_error_message_contains_hint_and_server_message():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(401, json={"message": "API key expired"})
+    client = _client(handler)
+    with pytest.raises(AxmeAuthError) as exc_info:
+        client.health()
+    msg = str(exc_info.value)
+    assert "API key invalid" in msg
+    assert "API key expired" in msg
+