Error handling - Amazon SDK for Kotlin
Service exceptionsClient exceptionsError metadata
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).

Error handling

Understanding how and when the Amazon SDK for Kotlin 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.

Service exceptions

The most common exception is AwsServiceException, from which all service-specific exceptions (such as S3Exception) inherit. This exception represents 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 returns an error response. The error response details are included in the AwsServiceException that’s thrown.

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

Client exceptions

ClientException indicates that a problem occurred inside the Amazon SDK for Kotlin client code, either while trying to send a request to Amazon or while trying to parse a response from Amazon. A ClientException is generally more severe than an AwsServiceException and indicates that a major problem is preventing the client from processing service calls to Amazon Web Services services. For example, the Amazon SDK for Kotlin throws a ClientException if it fails to parse a response from a service.

Error metadata

Every service exception and client exception has the sdkErrorMetadata property. This is a typed property bag that can be used to retrieve additional details about the error.

Several predefined extensions exist to the AwsErrorMetadata type directly, including but not limited to the following:

  • sdkErrorMetadata.requestId – the unique request id

  • sdkErrorMetadata.errorMessage – the human readable message (usually matches the Exception.message, but might contain more information if the exception was unknown to the service)

  • sdkErrorMetadata.protocolResponse – The raw protocol response

The following example demonstrates accessing the error metadata.

try {
    s3Client.listBuckets { ... }
} catch (ex: S3Exception) {
    val awsRequestId = ex.sdkErrorMetadata.requestId
    val httpResp = ex.sdkErrorMetadata.protocolResponse as? HttpResponse

    println("requestId was: $awsRequestId")
    println("http status code was: ${httpResp?.status}")
}