Need clear info and examples on proper error handling

It's very difficult for people to understand the error handling behavior of the client library, and how to properly handle errors. The async methods make it even more difficult. Information is spread across multiple sections, hidden in individual method descriptions, or else not mentioned at all. The docs should provide a clear description of how to use the API correctly, including example code that does correct error handling that can be cut-and-pasted.

There is a brief mention of error handling here, but it's hidden and very cursory, with no example code:
http://www.couchbase.com/docs/couchbase-sdk-java-1.1/create-update-docs.html

This doc mentions that .get() returns null on failure, but gives no hints on how to determine why, or what the right way to recover is:
http://www.couchbase.com/docs/couchbase-sdk-java-1.1/read-docs.html

This gives a very cursory mention of failure, but no way to get further details:
http://www.couchbase.com/docs/couchbase-sdk-java-1.1/delete-docs.html

No mention of JSON encoding errors or what to expect:
http://www.couchbase.com/docs/couchbase-sdk-java-1.1/json-handling-docs.html

Mentions that OperationFuture may return false even if operation succeeds due to durability requirement failure, but no clear example of how to tell the difference, what status codes to expect in each case, etc.:
http://www.couchbase.com/docs/couchbase-sdk-java-1.1/advanced-persistence.html

Mentions that synchronous call may return an exception, but no info on what the exception would be, or in what circumstances it may return null with no exception:
http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-summary-synchronous.html

No mention of .isSuccess() method, or any info on how errors are reported via *Future objects. Also no mention of when the async method may fail immediately vs. when the failure will be reported only after checking .isSuccess() or another method on the future. No mention of what errors are reported as exceptions vs. what errors are reported only via the future object's methods.:
http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-summary-asynchronous.html

No mention of when the constructor might fail or what exceptions might be thrown:
http://www.couchbase.com/docs/couchbase-sdk-java-1.1/api-reference-connection.html

No mention of how to tell if the FALSE result is due to timeout, impossible persistence requirements, or other problem:
http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-set-observe.html

Not clear enough that .add(), .set(), .replace() are an async methods, too easy for new user to misunderstand how to use them:
http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-set-add.html
http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-set-set.html
http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-update-replace.html

No mention that .get() may throw an exception, or how errors other than NotFound may be reported:
http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-retrieve-get.html

Yay, here is an example that has a bit of error handling! Unfortunately, it is a "catch(Exception)" (i.e., very generic, and not intended to catch Couchbase-specific errors or timeouts), and no indication of how to handle actual Couchbase errors. Also gives false impression that get() will throw an exception on all failure, when in fact you need to check for failure with .isSuccess() or something.:
http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-retrieve-get-async.html

Also on that page (async get), mentions that a TimeoutException may be thrown. But that won't happen on asyncGet() call, instead it will be when checking .get() on the Future result. I think. It is welcome to list exceptions that can be thrown, but I think this one is incorrect.
http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-retrieve-get-async.html

.getBulk() and .asyncGetBulk() are complicated enough that they deserve their own example of proper error handling, and what happens when one server node is down and other nodes are up, so partial results are available, etc.:
http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-retrieve-bulk.html

Nice that these pages mention what exceptions can be thrown, so I can infer how to tell a timeout from a not found, etc. But why only here? Shouldn't these exceptions be more generally described elsewhere as applying to all operations (RuntimeException, InterruptedException, OperationTimeoutException)?:
http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-retrieve-get-and-lock.html
http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-retrieve-unlock.html

Append and Prepend should normally use 0 for the casunique, and then I would not expect an EXISTS error. The example code is clunky, less efficient (suggests doing a .gets() call just to get the cas id), and likely to fail much more often. The example code does not do proper retry handling on an EXISTS error. It does not show how to distinguish an EXISTS, NOTFOUND, or server down error.:
http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-update-append.html
http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-update-prepend.html

View queries might time out, on all or some servers. Should document how the client should handle errors from view queries. Also, if client requests a view that doesn't exist, how is that handled:
http://www.couchbase.com/docs/couchbase-sdk-java-1.1/api-reference-view.html

There is no mention of error handling in the "Using the APIs" nor "Java Troubleshooting" sections, either:

http://www.couchbase.com/docs/couchbase-sdk-java-1.1/api-reference-started.html
http://www.couchbase.com/docs/couchbase-sdk-java-1.1/api-reference-troubleshooting.html

There is a brief mention of RuntimeException being "returned" (should say "thrown") in the section on handling timeouts, but this is too buried and too specific to be of real use. And there is no example code:
http://www.couchbase.com/docs/couchbase-sdk-java-1.1/api-reference-troubleshooting.html

Also, the tutorial doesn't do error handling at all, for example:

http://www.couchbase.com/docs/couchbase-sdk-java-1.1/managing-beers.html

Look for "client.set" and "client.query" on that page and you'll see it ignores error handling entirely. I think this is a mistake in tutorial code, it should be complete and correct, or at least it should provide a warning saying that there is no error handling, with a link to the docs that describe how to do proper error handling.