DynamoDB ClientRequestToken 8-hour TTL: handling retries after token expiry

What happens after the 8‑hour TTL?

Confirmed fact: DynamoDB caches ClientRequestToken for PutItem, UpdateItem and DeleteItem for up to 8 hours. Within that window a retry with the same token returns the original response and does not re‑execute the write. After the token is purged the service treats the request as a new write, which can create duplicate items or overwrite attributes if the original write succeeded but the response was lost.

Likely explanation

The token store is internal and not configurable; there is no way to extend or inspect its TTL. Therefore, to achieve exactly‑once semantics for retries that may occur days later you must add application‑level deduplication that does not rely on the token.

Steps for each API

1. PutItem / UpdateItem / DeleteItem
   • Create a dedicated deduplication table (or reuse an existing table) with a primary key that is the ClientRequestToken (or a hash of it) and a sort key for the timestamp.
   • Before issuing the write, perform a ConditionExpression that checks attribute_not_exists(pk) (or checks a version attribute you expect).
   • If the condition fails, treat the operation as a duplicate and return the stored response (you can retrieve it from the dedup table or re‑read the item).
   • On success, write the item and also write a record to the dedup table with the token and a TTL far beyond 8 hours (e.g., 7 days) so that future retries are detected.
2. TransactWriteItems
   • TransactWriteItems does not accept ClientRequestToken, so idempotency must be built into the transaction.
   • Add a ConditionCheck on a dedicated idempotency attribute (e.g., #id = :expected) for each item you want to protect.
   • The transaction should first attempt to write the item with a condition like attribute_not_exists(#id) or a version check. If the condition fails, the whole transaction is rejected, which you can treat as a duplicate.
   • Optionally, write a separate idempotency record (token → timestamp) in the same transaction using a Put with a condition that the token does not already exist.
3. Global Tables
   • Tokens are not replicated, so a retry in a different region after the local TTL expiry can diverge.
   • Use a globally replicated deduplication table (the same table name in every region) or a version attribute that is updated with each write.
   • Apply the same conditional‑check pattern as above; because the table is replicated, the condition will be evaluated against the latest state across regions, preventing divergent writes.
   • If you cannot rely on a version attribute, store the token with a long TTL in the dedup table and let the conditional Put guard against duplicates in every region.

Verification steps

1. Within 8 hours: retry a PutItem with the same token and confirm the response is identical and the item count has not increased (check via Scan or Streams).
2. After >8 hours: repeat the retry; observe a new item version or a new record in Streams, indicating a fresh write.
3. For the deduplication table approach: after a successful write, query the table for the token; a subsequent retry should find the existing record and cause the condition to fail.
4. For TransactWriteItems: execute the transaction twice with the same idempotency key; the second attempt should be rejected with a ConditionalCheckFailedException.

Missing diagnostic detail

Do you have an existing attribute (such as a version number, UUID, or business key) that can be used in a ConditionExpression to detect whether the write has already been applied? If yes, you can rely on that attribute for deduplication; if not, you must introduce a separate deduplication table as described.