DynamoDB PutItem Retry Compatibility: Adding Cross-Attempt Idempotency

Change boundary

The goal is to define an application-level idempotency contract for DynamoDB PutItem retries when a transient failure or lost response leaves the client unable to tell whether the write committed. The documented single-item API does not provide a cross-attempt idempotency token, so a client-side retry can repeat an already successful write.

The design must distinguish a first attempt from a retry, preserve the same logical request identifier across attempts, and define how conditional failures affect capacity usage, batch processing, and response handling. It must also set retention for idempotency metadata without allowing it to grow indefinitely. The DynamoDB API behavior is stable across current API versions; SDK retry defaults and exception classification vary by language and package version, so the selected SDK version must be identified before finalizing the contract.

Which request-identifier placement and conditional-write contract fit PutItem while keeping the item schema compatible?

Should a conditional failure be treated as success, and how should capacity consumption and batch retries be surfaced?

Which verification cases should cover timeout-after-commit, duplicate request identifiers, and conditional failure handling in the selected SDK version, and what retention policy should bound idempotency metadata?