DynamoDB IdempotentParameterMismatchException

TL;DR — You called TransactWriteItems with a ClientRequestToken that was already used in the last 10 minutes, but the rest of the request changed. The token promises "this is the same transaction, retried" — so DynamoDB rejects a token reuse whose payload differs. Reuse the token only for byte-identical retries; mint a fresh token (a UUID) for every new logical transaction.

What it means

IdempotentParameterMismatchException: DynamoDB rejected the request because
you retried a request with a different payload but with an idempotent token
that was already used.

ClientRequestToken makes TransactWriteItems idempotent: multiple identical calls with the same token have the effect of a single call, which protects you from double-applying a transaction when a timeout hides whether the first attempt landed. A token stays valid for 10 minutes after the first request that used it completes. If a request arrives inside that window with the same token but different parameters, DynamoDB can't treat it as a retry — and refuses to treat it as a new transaction either. HTTP 400, not retryable as-is.

Why it happens

• A static or hardcoded token — the same token string is sent for every transaction, so the second (different) transaction collides with the first.
• Token derived from something too coarse — e.g. the user ID or table name, so two different transactions for the same user share a token.
• The retry rebuilt the request differently — a timestamp, TTL value, or generated ID inside an item changed between attempt one and the retry, so the "same" transaction no longer matches byte-for-byte.
• Two code paths share a token source — parallel workers seeded with the same value.

How to fix it

1. Generate a unique token per logical transaction — a UUID at the point where the transaction is composed:

   import {randomUUID} from 'node:crypto';
   
   await client.send(new TransactWriteItemsCommand({
     ClientRequestToken: token, // created ONCE per logical transaction
     TransactItems: [...]
   }));

2. Keep the token with the request when retrying — retry the same already-built request object, not a rebuilt one, so nothing in the payload can drift. (The AWS SDKs do this correctly for their automatic retries; the bug is almost always an application-level retry that recomposes the request.)

3. Pin volatile values before composing — timestamps and generated IDs must be computed once and reused on retry, not re-evaluated.

4. Don't reuse a token after 10 minutes expecting idempotency — past the window the request is treated as brand-new and will be applied again.

The DynoTable desktop app lets you inspect the exact items a transaction touched, which makes "did my first attempt actually land?" a lookup instead of a guess.

Related errors

• TransactionCanceledException — the transaction ran and was rolled back.
• TransactionConflictException — a concurrent transaction touched the same item.
• TransactWriteItems: too many items
• Code example: TransactWriteItems in Node.js — shows ClientRequestToken usage.
• Learn: DynamoDB transactions

References

• TransactWriteItems — Amazon DynamoDB API Reference (ClientRequestToken, IdempotentParameterMismatchException)
• Amazon DynamoDB Transactions: How it works — Developer Guide (idempotency)
• Error handling with DynamoDB — Amazon DynamoDB Developer Guide

Last verified 2026-07-13 against the official AWS documentation linked above.