There's nothing wrong with the API. It's simply the case that cluster failover in Lotus Notes and Domino is designed for Domino's proprietary network protocol (NRPC). The Notes client uses NRPC. That's why it can do failover. Java code that uses notes.jar instead of NCSO.jar can do it, too, because it also uses NRPC -- and some under-the-covers Notes client config info.
But it is not going to work with NCSO.jar, because that's using IIOP.
Here's why this is the case. In general, standard protocols don't know anything about any type of clustering. Solutions for clustering those standard protocols pretty much all rely on some sort of high-availability network device to direct traffic to the various servers in the cluster. But unlike clustering solutions for standard protocols, Domino clustering works without any external load balancer/failover device on the network. So if the Domino server is in a cluster, but it's not responding, how does the Notes client know the address of another server to fail over to? There's no traffic-cop device to talk to, and it obviously can't ask the server because it's not responding. So it has to look at configuration information that has already been stored locally to tell it what other servers with replicas of the target database are available! That information is maintained by the Notes core DLLs that are part of the Notes client installation, so you have to have the Notes client installed for it to have any chance of working. But when you are using NCSO.jar, there is no assumption that there is a local Notes client. Even if you do have a Notes client installed, NCSO.jar is unaware of it. So there's no way for the IIOP-based Notes Java API classes to know where to look up any information about the available servers in the Domino cluster.
There is something called Domino Internet Cluster Manager that works for Domino HTTP failover, but I don't think that supports IIOP either. I'm not sure about that, though, so you might want to look into it. But I think that if you want IIOP failover, you will probably have to add a 3rd party load balance/clustering solution to your network. The good news there, though, is that you probably won't need any special APIs to take advantage of that. Or, if you don't have a clustering solution that supports IIOP on your network and you can't add one, then you can just program your code to work with multiple servers. Write your code so that instead of just having one server name/address programmed into it, it has several, and try opening your database on them in order until you succeed.