Exception handling for the Amazon SDK for Java 2.x - Amazon SDK for Java 2.x
Why unchecked exceptions?AwsServiceException (and subclasses)SdkClientExceptionExceptions and retry behavior
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Exception handling for the Amazon SDK for Java 2.x

Understanding how and when the Amazon SDK for Java 2.x throws exceptions is important to building high-quality applications using the SDK. The following sections describe the different cases of exceptions that are thrown by the SDK and how to handle them appropriately.

Why unchecked exceptions?

The Amazon SDK for Java uses runtime (or unchecked) exceptions instead of checked exceptions for these reasons:

  • To allow developers fine-grained control over the errors they want to handle without forcing them to handle exceptional cases they aren’t concerned about (and making their code overly verbose)

  • To prevent scalability issues inherent with checked exceptions in large applications

In general, checked exceptions work well on small scales, but can become troublesome as applications grow and become more complex.

AwsServiceException (and subclasses)

AwsServiceException is the most common exception that you’ll experience when using the Amazon SDK for Java. AwsServiceException is a subclass of the more general SdkServiceException. AwsServiceExceptions represent an error response from an Amazon Web Services service. For example, if you try to terminate an Amazon EC2 instance that doesn’t exist, Amazon EC2 will return an error response and all the details of that error response will be included in the AwsServiceException that’s thrown.

When you encounter an AwsServiceException, you know that your request was successfully sent to the Amazon Web Services service but couldn’t be successfully processed. This can be because of errors in the request’s parameters or because of issues on the service side.

AwsServiceException provides you with information such as:

  • Returned HTTP status code

  • Returned Amazon error code

  • Detailed error message from the service in the AwsErrorDetails class

  • Amazon request ID for the failed request

In most cases, a service-specific subclass of AwsServiceException is thrown to allow developers fine-grained control over handling error cases through catch blocks. The Java SDK API reference for AwsServiceException displays the large number of AwsServiceException subclasses. Use the subclass links to drill down to see the granular exceptions thrown by a service.

For example, the following links to the SDK API reference show the exception hierarchies for a few common Amazon Web Services services. The list of subclasses shown on each pages shows the specific exceptions that your code can catch.

To learn more about an exception, inspect the errorCode on the AwsErrorDetails object. You can use the errorCode value to look up information in the service guide API. For example if an S3Exception is caught and the AwsErrorDetails#errorCode() value is InvalidRequest, use the list of error codes in the Amazon S3 API Reference to see more details.

SdkClientException

SdkClientException indicates that a problem occurred inside the Java client code, either while trying to send a request to Amazon or while trying to parse a response from Amazon. An SdkClientException is generally more severe than an SdkServiceException, and indicates a major problem that is preventing the client from making service calls to Amazon services. For example, the Amazon SDK for Java throws an SdkClientException if no network connection is available when you try to call an operation on one of the clients.

Exceptions and retry behavior

The SDK for Java retries requests for several client-side exceptions and for HTTP status codes that it receives from Amazon Web Services service responses. These errors are handled as part of the legacy RetryMode that service clients use by default. The Java API reference for RetryMode describes the various ways that you can configure the mode.

To customize the exceptions and HTTP status codes that trigger automatic retries, configure your service client with a RetryPolicy that adds RetryOnExceptionsCondition and RetryOnStatusCodeCondition instances.