Why catch exceptions from AWS and Boto¶

• Service limits and quotas - Your call rate to an AWS service might be too frequent, or you might have reached a specific AWS service quota. In either case, without proper error handling you wouldn’t know or wouldn’t handle them.

• Parameter validation and checking - API requirements can change, especially across API versions. Catching these errors helps to identify if there’s an issue with the parameters you provide to any given API call.

• Proper logging and messaging - Catching errors and exceptions means you can log them. This can be instrumental in troubleshooting any code you write when interacting with AWS services.

Botocore exceptions¶

These exceptions are statically defined within the botocore package, a dependency of Boto3. The exceptions are related to issues with client-side behaviors, configurations, or validations. You can generate a list of the statically defined botocore exceptions using the following code:

importbotocore.exceptionsforkey,valueinsorted(botocore.exceptions.__dict__.items()):ifisinstance(value,type):print(key)

AliasConflictParameterErrorApiVersionNotFoundErrorBaseEndpointResolverErrorBotoCoreErrorChecksumErrorClientErrorConfigNotFoundConfigParseErrorConnectTimeoutErrorConnectionClosedErrorConnectionErrorCredentialRetrievalErrorDataNotFoundErrorEndpointConnectionErrorEventStreamErrorHTTPClientErrorImminentRemovalWarningIncompleteReadErrorInfiniteLoopConfigErrorInvalidConfigErrorInvalidDNSNameErrorInvalidExpressionErrorInvalidMaxRetryAttemptsErrorInvalidRetryConfigurationErrorInvalidS3AddressingStyleErrorInvalidS3UsEast1RegionalEndpointConfigErrorInvalidSTSRegionalEndpointsConfigErrorMD5UnavailableErrorMetadataRetrievalErrorMissingParametersErrorMissingServiceIdErrorNoCredentialsErrorNoRegionErrorOperationNotPageableErrorPaginationErrorParamValidationErrorPartialCredentialsErrorProfileNotFoundProxyConnectionErrorRangeErrorReadTimeoutErrorRefreshWithMFAUnsupportedErrorSSLErrorServiceNotInRegionErrorStubAssertionErrorStubResponseErrorUnStubbedResponseErrorUndefinedModelAttributeErrorUnknownClientMethodErrorUnknownCredentialErrorUnknownEndpointErrorUnknownKeyErrorUnknownParameterErrorUnknownServiceErrorUnknownServiceStyleUnknownSignatureVersionErrorUnseekableStreamErrorUnsupportedS3AccesspointConfigurationErrorUnsupportedS3ArnErrorUnsupportedSignatureVersionErrorUnsupportedTLSVersionWarningValidationErrorWaiterConfigErrorWaiterError

AWS service exceptions¶

AWS service exceptions are caught with the underlying botocore exception,ClientError. After you catch this exception, you can parse through the response for specifics around that error, including the service-specific exception. Exceptions and errors from AWS services vary widely. You can quickly get a list of an AWS service’s exceptions using Boto3.

For a complete list of error responses from the services you’re using, consult the individual service’sAWS documentation, specifically the error response section of the AWS service’s API reference. These references also provide context around the exceptions and errors.

Catching botocore exceptions¶

Botocore exceptions are statically defined in the botocore package. Any Boto3 clients you create will use these same statically defined exception classes. The most common botocore exception you’ll encounter isClientError. This is a general exception when an error response is provided by an AWS service to your Boto3 client’s request.

Additional client-side issues with SSL negotiation, client misconfiguration, or AWS service validation errors will also throw botocore exceptions. Here’s a generic example of how you might catch botocore exceptions.

importbotocoreimportboto3client=boto3.client('aws_service_name')try:client.some_api_call(SomeParam='some_param')exceptbotocore.exceptions.ClientErroraserror:# Put your error handling logic hereraiseerrorexceptbotocore.exceptions.ParamValidationErroraserror:raiseValueError('The parameters you provided are incorrect:{}'.format(error))

Parsing error responses and catching exceptions from AWS services¶

Unlike botocore exceptions, AWS service exceptions aren’t statically defined in Boto3. This is due to errors and exceptions from AWS services varying widely and being subject to change. To properly catch an exception from an AWS service, you must parse the error response from the service. The error response provided to your client from the AWS service follows a common structure and is minimally processed and not obfuscated by Boto3.

Using Boto3, the error response from an AWS service will look similar to a success response, except that anError nested dictionary will appear with theResponseMetadata nested dictionary. Here is an example of what an error response might look like:

{'Error':{'Code':'SomeServiceException','Message':'Details/context around the exception or error'},'ResponseMetadata':{'RequestId':'1234567890ABCDEF','HostId':'host ID data will appear here as a hash','HTTPStatusCode':400,'HTTPHeaders':{'header metadata key/values will appear here'},'RetryAttempts':0}}

Boto3 classifies all AWS service errors and exceptions asClientError exceptions. When attempting to catch AWS service exceptions, one way is to catchClientError and then parse the error response for the AWS service-specific exception.

Using Amazon Kinesis as an example service, you can use Boto3 to catch the exceptionLimitExceededException and insert your own logging message when your code experiences request throttling from the AWS service.

importbotocoreimportboto3importlogging# Set up our loggerlogging.basicConfig(level=logging.INFO)logger=logging.getLogger()client=boto3.client('kinesis')try:logger.info('Calling DescribeStream API on myDataStream')client.describe_stream(StreamName='myDataStream')exceptbotocore.exceptions.ClientErroraserror:iferror.response['Error']['Code']=='LimitExceededException':logger.warn('API call limit exceeded; backing off and retrying...')else:raiseerror

Additionally, you can also access some of the dynamic service-side exceptions from the client’s exception property. Using the previous example, you would need to modify only theexcept clause.

exceptclient.exceptions.LimitExceedExceptionaserror:logger.warn('API call limit exceeded; backing off and retrying...')