Exception handling in the Open World platform SDK for Java

The Open World platfrom SDK for Java uses runtime (unchecked) exceptions to relay errors. At the root of the exception hierarchy is OpenWorldException, from which all other exceptions are extended. OpenWorldException is never thrown directly.

There are two categories of an OpenWorldException:

1. OpenWorldServiceException: thrown when the downstream service returns an error response; that is, the service successfully received the request, but it was not able to process it. The exception object provides the caller with several pieces of information about the error, including an HTTP status code and a detailed message. OpenWorldAuthException is a subtype of this exception, and it is thrown when authentication fails.

2. OpenWorldClientException: thrown at client errors, either when trying to send the request or parse the response. For example, an OpenWorldConfigurationException is thrown if credentials are not configured.

Since exceptions are unchecked, the caller decided which exceptions to handle. In principle, an OpenWorldClientException is assumed to be not retryable, and they should be typically fixed during development. An OpenWorldServiceException, on the other hand, might be recoverable, such as errors resulting from a service being temporarily unavialable. Error handling should therefore focus on the latter.