Error Handling

dkmio maps standard DynamoDB ClientError codes to specific, meaningful Python exceptions. All dkmio exceptions inherit from the base DkmioError.

Common Exceptions

Exception	DynamoDB Error / Description
DkmioError	Base class for all errors in the library.
MissingKeyError	Raised when a required key (PK or SK) is missing in a get() call.
InvalidProjectionError	Raised when requesting attributes not available in a GSI/LSI projection.
ConditionError	Maps to ConditionalCheckFailedException.
TableNotFoundError	Maps to ResourceNotFoundException.
ValidationError	Maps to ValidationException (malformed expressions, etc.).
ThrottlingError	Maps to ProvisionedThroughputExceededException.
CollectionSizeError	Maps to ItemCollectionSizeLimitExceededException.
TransactionError	Maps to TransactionCanceledException.

Examples

Handling Conditional Writes

Conditional writes are a common source of errors when implementing optimistic locking or idempotency.

from dkmio import ConditionError

try:
    orders.put(
        user_id="usr_123", 
        order_id="ord_789",
        status="NEW",
        condition={"user_id__not_exists": True}
    )
except ConditionError:
    print("Conflict: Order already exists.")

Handling Missing Keys

If you try to use get() without providing the full primary key (Partition Key + Sort Key if defined), dkmio will remind you to use query() instead.

from dkmio import MissingKeyError

try:
    # This raises MissingKeyError if Orders has an SK
    order = orders.get(user_id="usr_123")
except MissingKeyError as e:
    print(e)  
    # Output: "get() requires the full key. Missing: order_id. 
    # Use .query() to search by partition key."

Throttling and Retries

While dkmio's batch operations (batch_write, batch_read) automatically handle retries with exponential backoff for unprocessed items, individual operations might still fail if capacity is consistently exceeded.

from dkmio import ThrottlingError

try:
    orders.put(...)
except ThrottlingError:
    # Capacity exceeded, implement your own retry or queue logic
    print("DynamoDB is throttled. Please try again later.")