(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

Metadata

Release files for boto3-errors 0.44.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for boto3-errors 0.44.0
File	Size	Uploaded
boto3_errors-0.44.0.tar.gz	335.2 kB	Oct 13, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for boto3-errors 0.44.0
File	Interpreter	ABI	Platform	Reset
boto3_errors-0.44.0-py3-none-any.whl 582.7 kB Oct 13, 2026	Python 3	none	any	Details

Total release size: 917.9 kB

Release files / boto3_errors-0.44.0.tar.gz

Download URL	boto3_errors-0.44.0.tar.gz
Size	335.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`e0e37f2b74fa81cfa21565f4e204411d0d4682cdd262453f99a74484fe55167b`
BLAKE2b-256 checksum How to use checksums	`69e2adcb5acdd2ce431a0ee267557da6777235087810a2a6243ec01f20c8cd93`
Upload date	Oct 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / boto3_errors-0.44.0-py3-none-any.whl

Download URL	boto3_errors-0.44.0-py3-none-any.whl
Size	582.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`4720990590435965439f6f03768f811b1c8b865778a4073b733fccef1a3fd4b5`
BLAKE2b-256 checksum How to use checksums	`dd7ed24eb95a2a9763ee55e6dc3df8ce45acfe8a5f4194bb9a1e207a0cf49df6`
Upload date	Oct 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`