Add documentation for the JetStreamApiException thrown from the KeyValue.update method

[senior]

Proposed change

There should be more documentation around exactly what is thrown when there is an optimistic locking failure related to the KeyValue update method.

Use case

I want to make sure that a "write after write" collision doesn't happen when updating a key. The way that I read to do that via optimistic locking was the update method. So in my case, if the value has changed since it was last read, I would want to fail and retry to apply a change to that key's value. The way that I do that is to catch the JetStreamApiException, then reread the value and retry the update. It's not clear from the docs what other things could potentially throw that JetStreamApiException. If something that was non-recoverable threw that exception and I just always retried if update threw that exception, I could get caught in an infinite loop. I would like some additional documentation that either confirmed that exception is only thrown from the update method if there is an optimistic locking failure, or that I need to also check some other error code so that I don't retry forever.

Contribution

I'm not intending to contribute docs for this but am writing it up based on a conversation I had with Scott Fauerbach.