fix: raise RateLimitError on 429 so FastMCP sets isError in MCP response

Add RateLimitError exception class for 429 responses from the
duplication API. This propagates through FastMCP as isError: true,
enabling the Next.js proxy to detect and retry rate-limited requests.

Author: nictuku

meta_ads_mcp/core/duplication.py

@@ -13,6 +13,11 @@
 logger = logging.getLogger(__name__)
 
 
+class RateLimitError(Exception):
+    """Raised on 429 so FastMCP sets isError: true in the MCP response."""
+    pass
+
+
 # Only register the duplication functions if the environment variable is set
 ENABLE_DUPLICATION = bool(os.environ.get("META_ADS_ENABLE_DUPLICATION", ""))
 
@@ -368,14 +373,16 @@ async def _forward_duplication_request(resource_type: str, resource_id: str, acc
                     "suggestion": f"Verify the {resource_type} ID and your Facebook account permissions"
                 }, indent=2)
             elif response.status_code == 429:
-                return json.dumps({
-                    "error": "rate_limit_exceeded", 
+                # Raise so FastMCP sets isError: true in MCP response,
+                # enabling the Next.js proxy to detect and retry.
+                raise RateLimitError(json.dumps({
+                    "error": "rate_limit_exceeded",
                     "message": "Meta API rate limit exceeded",
                     "details": {
                         "suggestion": "Please wait before retrying",
                         "retry_after": response.headers.get("Retry-After", "60")
                     }
-                }, indent=2)
+                }, indent=2))
             elif response.status_code == 502:
                 try:
                     error_data = response.json()
@@ -443,6 +450,9 @@ async def _forward_duplication_request(resource_type: str, resource_id: str, acc
             }
         }, indent=2)
 
+    except RateLimitError:
+        raise  # Let FastMCP handle this to set isError: true
+
     except Exception as e:
         return json.dumps({
             "error": "unexpected_error",

tests/test_duplication_regression.py

@@ -307,27 +307,26 @@ async def test_http_status_code_handling(self, enable_feature):
                     mock_response.text = f"Error {status_code}"
 
                 mock_client.return_value.__aenter__.return_value.post.return_value = mock_response
-                
-                result = await duplication._forward_duplication_request(
-                    "campaign", "123", "token", {}
-                )
-                result_json = json.loads(result)
-                
-                if response_type == "error":
-                    if status_code == 401:
-                        assert result_json["error"] == expected_error_type
-                    elif status_code == 403:
-                        assert result_json["error"] == expected_error_type
-                    elif status_code == 400:
-                        assert result_json["error"] == expected_error_type
-                    elif status_code == 404:
-                        assert result_json["error"] == expected_error_type
-                    elif status_code == 502:
+
+                if status_code == 429:
+                    # 429 raises RateLimitError so FastMCP sets isError: true
+                    from meta_ads_mcp.core.duplication import RateLimitError
+                    with pytest.raises(RateLimitError) as exc_info:
+                        await duplication._forward_duplication_request(
+                            "campaign", "123", "token", {}
+                        )
+                    exc_json = json.loads(str(exc_info.value))
+                    assert exc_json["error"] == expected_error_type
+                else:
+                    result = await duplication._forward_duplication_request(
+                        "campaign", "123", "token", {}
+                    )
+                    result_json = json.loads(result)
+
+                    if response_type == "error":
                         assert result_json["error"] == expected_error_type
                     else:
-                        assert result_json["error"] == expected_error_type
-                else:
-                    assert "success" in result_json or "id" in result_json
+                        assert "success" in result_json or "id" in result_json
 
     @pytest.mark.asyncio
     async def test_network_error_handling(self, enable_feature):