(Better) boto3 errors

Typed, statically-importable exception classes for every AWS service.

Install

pip install boto3-errors

Quick start

import boto3
from boto3_errors import patch_client
from boto3_errors.dynamodb import ConditionalCheckFailedException

client = boto3.client("dynamodb")
patch_client(client)

try:
    client.put_item(
        TableName="users",
        Item={"pk": {"S": "user#1"}, "name": {"S": "Ada"}},
        ConditionExpression="attribute_not_exists(pk)",
    )
except ConditionalCheckFailedException as e:
    print(e.message)  # "The conditional request failed"
    print(e.error_code)  # "ConditionalCheckFailedException"
    print(e.item)  # {"pk": {"S": "user#1"}, "name": {"S": "Ada"}}

The problem

Every boto3 error comes back as a ClientError. The only way to distinguish them is by parsing e.response["Error"]["Code"] — a stringly-typed dict lookup with no autocomplete, no type checking, and no IDE support. A typo in the error code string won't be caught until it crashes.

What you get

All AWS services with exception classes auto-generated from botocore's service model.

Exception hierarchy

ClientError                     # botocore base — still works
└── Boto3Error                  # boto3-errors base
    └── DynamoDBError           # per-service base
        ├── ConditionalCheckFailedException
        ├── ResourceNotFoundException
        ├── TransactionCanceledException
        └── ...

Every exception is a ClientError subclass, so existing except ClientError handlers keep working.

Built-in properties

Every Boto3Error exposes:

Property	Type	Source
message	str	Error.Message
error_code	str	Error.Code
http_status_code	int	ResponseMetadata.HTTPStatusCode
request_id	str	ResponseMetadata.RequestId

Service-specific properties

Some exceptions expose extra fields from the API response:

from boto3_errors.dynamodb import (
    ConditionalCheckFailedException,
    TransactionCanceledException,
)

# ConditionalCheckFailedException.item -> dict | None
# TransactionCanceledException.cancellation_reasons -> list | None