aws-error-utils

What it is and what it does

aws-error-utils simplifies exception handling for botocore by converting opaque ClientError objects into Pythonic exception classes and named tuples. When botocore raises a ClientError, all error details are buried in nested dictionaries (e.g., error.response['Error']['Code'], error.response['Error']['Message']); this package exposes them as direct attributes (error.code, error.message, error.http_status_code, error.operation_name) and lets you catch specific AWS error codes as exception types (e.g., except errors.NoSuchBucket) rather than inspecting dictionary contents.

The package provides three main interfaces: the `errors` class for simple error-code matching in except blocks, the `catch_aws_error()` function for more complex conditions (including regex matching or operation-name filtering), and the `get_aws_error_info()` function to extract error metadata from any ClientError. It requires only botocore as a dependency and supports Python 3.7 through 3.11.

Use it for:

• Catch specific error codes like NoSuchBucket or NoSuchKey without parsing nested dictionaries in except blocks.
• Match errors by both error code and operation name when multiple API calls exist in a single try block.
• Extract HTTP status codes and error messages from ClientError for logging or custom error reporting.
• Use regex or custom callables to match errors based on message content rather than just error codes.
• Reduce boilerplate in exception handling code that calls multiple AWS services.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Wraps botocore ClientError exceptions to provide Pythonic access to error codes, messages, HTTP status codes, and operation names without navigating nested dictionaries.

Yes. The package is lightweight (pure Python, one dependency), production-stable, carries no security vulnerabilities, and meaningfully reduces error-handling boilerplate. Dormant maintenance is not a concern because error handling for existing AWS services rarely changes. Install it if you write botocore code with more than a few try-except blocks.

Install

aws-error-utils on PyPI

pip install aws-error-utils

uv add aws-error-utils

poetry add aws-error-utils

Installing aws-error-utils

Before you install

Low friction: pure Python wheel with only botocore as a runtime dependency. Maintenance is dormant (last release 2022-11-03, no commits since 2023-11-11), but the package is marked Production/Stable and has no known vulnerabilities, suggesting it is feature-complete rather than abandoned.

License in practice

Apache-2.0 is permissive; you may use, modify, and distribute this package freely in commercial and private projects, provided you retain the license notice.

Quickstart

from aws_error_utils import errors, catch_aws_error, get_aws_error_info

# Catch by error code as exception type
except errors.NoSuchBucket as error:
    print(error.message)

# Or use catch_aws_error() for complex matching
except catch_aws_error('NoSuchBucket') as error:
    print(error.code, error.http_status_code)

Verify before relying

• Whether error code tab completion is available in modern IDEs despite the lack of a comprehensive botocore error code registry.
• Performance characteristics when using catch_aws_error() with multiple error codes versus the errors class.

Package facts

Evidence: aws_error_utils-2.7.0-py3-none-any.whl

Tags

More Utilities packages