---
id: aws-error-utils
version: "2.7.0"
license: Apache-2.0
license_treatment: permissive
maintenance: dormant
---

# aws-error-utils — Error-handling functions for boto3/botocore

License: permissive · Maintenance: dormant · Downloads: 376.4K/mo

## 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 above — 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

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

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: dormant
- Downloads: 376.4K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

boto3 error handling, botocore exception wrapper, AWS error code matching, ClientError parsing, AWS error info extraction, botocore error codes, exception utilities, aws, error-handling

[View on SkillFed](https://skillfed.io/packages/aws-error-utils) · [View on PyPI](https://pypi.org/project/aws-error-utils/)