Exception handling for the AWS SDK for Java 2.x
Understanding how and when the AWS 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 AWS 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)
AwsServiceExceptionAwsServiceException
is a subclass of the
more general SdkServiceExceptionAwsServiceException
s represent an error
response from an AWS 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 AWS 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 AWS error code
-
Detailed error message from the service in the AwsErrorDetails
class -
AWS 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 AwsServiceExceptionAwsServiceException
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 AWS 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 AwsErrorDetailserrorCode
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
SdkClientExceptionSdkClientException
is generally more
severe than an SdkServiceException
, and indicates a major problem that is
preventing the client from making service calls to AWS services. For
example, the AWS 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 exceptionsRetryMode
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.