Skip to content

java-dg-exceptions.rst

Latest commit

 

History

History
83 lines (56 loc) · 3.91 KB

java-dg-exceptions.rst

File metadata and controls

83 lines (56 loc) · 3.91 KB
Raw

Exception Handling

Understanding how and when the AWS SDK for Java throws exceptions is important in order to build 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 AWS Java SDK uses runtime (or unchecked) exceptions instead of checked exceptions for a few 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.

For more information about the use of checked and unchecked exceptions, see the following articles:

AmazonServiceException (and Subclasses)

:java-api:`AmazonServiceException` is the most common exception that you'll experience when using the |sdk-java|. This exception represents an error response from an AWS service. For example, if you try to terminate an |EC2| instance that doesn't exist, EC2 will return an error response and all the details of that error response will be included in the thrown :classname:`AmazonServiceException`. For some cases, a subclass of :classname:`AmazonServiceException` will be thrown to allow developers fine grained control over handling error cases through catch blocks.

When you encounter an :classname:`AmazonServiceException`, you know that your request was successfully sent to the AWS service, but could not be successfully processed either because of errors in the request's parameters or because of issues on the service side.

:classname:`AmazonServiceException` provides you with information such as:

  • Returned HTTP status code
  • Returned AWS error code
  • Detailed error message from the service
  • AWS request ID for the failed request

:classname:`AmazonServiceException` also includes information about whether the failed request was the caller's fault (i.e., a request with illegal values) or the AWS service's fault (i.e., an internal service error).

AmazonClientException

:java-api:`AmazonClientException` indicates that a problem occurred inside the Java client code, either while trying to send a request to AWS or while trying to parse a response from AWS. :classname:`AmazonClientException` exceptions are generally more severe than :classname:`AmazonServiceException` exceptions and indicate a major problem that is preventing the client from being able to make service calls to AWS services. For example, the AWS Java SDK will throw an :classname:`AmazonClientException` if no network connection is available when you try to call an operation on one of the clients.