DynamoDB IdempotentParameterMismatchException

TL;DR — Du hast TransactWriteItems mit einem ClientRequestToken aufgerufen, das in den letzten 10 Minuten bereits verwendet wurde, aber der Rest der Anfrage hat sich geändert. Das Token verspricht „das ist dieselbe Transaktion, erneut versucht" — deshalb weist DynamoDB eine Token-Wiederverwendung ab, deren Payload abweicht. Verwende das Token nur für byte-identische Retries wieder; erzeuge ein frisches Token (eine UUID) für jede neue logische Transaktion.

Was es bedeutet

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

ClientRequestToken macht TransactWriteItems idempotent: mehrere identische Aufrufe mit demselben Token haben den Effekt eines einzelnen Aufrufs, was dich davor schützt, eine Transaktion doppelt anzuwenden, wenn ein Timeout verbirgt, ob der erste Versuch angekommen ist. Ein Token bleibt für 10 Minuten gültig, nachdem die erste Anfrage, die es verwendet hat, abgeschlossen ist. Wenn innerhalb dieses Fensters eine Anfrage mit demselben Token, aber anderen Parametern eintrifft, kann DynamoDB sie nicht als Retry behandeln — und weigert sich ebenso, sie als neue Transaktion zu behandeln. HTTP 400, so nicht wiederholbar.

Warum es passiert

• Ein statisches oder fest kodiertes Token — dieselbe Token-Zeichenkette wird für jede Transaktion gesendet, sodass die zweite (andere) Transaktion mit der ersten kollidiert.
• Token aus etwas zu Grobem abgeleitet — z. B. der User-ID oder dem Tabellennamen, sodass zwei verschiedene Transaktionen für denselben Nutzer ein Token teilen.
• Der Retry hat die Anfrage anders neu aufgebaut — ein Zeitstempel, TTL-Wert oder generierte ID innerhalb eines Items hat sich zwischen dem ersten Versuch und dem Retry geändert, sodass die „gleiche" Transaktion nicht mehr byte-für-byte übereinstimmt.
• Zwei Code-Pfade teilen sich eine Token-Quelle — parallele Worker, die mit demselben Wert initialisiert wurden.

So behebst du es

1. Erzeuge ein eindeutiges Token pro logischer Transaktion — eine UUID an der Stelle, an der die Transaktion zusammengesetzt wird:

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

2. Behalte das Token mit der Anfrage beim Wiederholen — wiederhole dasselbe bereits gebaute Anfrageobjekt, nicht ein neu aufgebautes, sodass nichts im Payload driften kann. (Die AWS SDKs machen das für ihre automatischen Retries korrekt; der Fehler ist fast immer ein anwendungsseitiger Retry, der die Anfrage neu zusammensetzt.)

3. Fixiere volatile Werte vor dem Zusammensetzen — Zeitstempel und generierte IDs müssen einmal berechnet und beim Retry wiederverwendet, nicht neu ausgewertet werden.

4. Verwende ein Token nach 10 Minuten nicht wieder in der Erwartung von Idempotenz — nach dem Fenster wird die Anfrage als brandneu behandelt und erneut angewendet.

Mit der DynoTable Desktop-App kannst du die exakten Items inspizieren, die eine Transaktion berührt hat, was „ist mein erster Versuch tatsächlich angekommen?" zu einem Lookup statt einer Vermutung macht.

Verwandte Fehler

• TransactionCanceledException — die Transaktion lief und wurde zurückgerollt.
• TransactionConflictException — eine gleichzeitige Transaktion hat dasselbe Item berührt.
• TransactWriteItems: zu viele Items
• Code-Beispiel: TransactWriteItems in Node.js — zeigt die Verwendung von ClientRequestToken.
• Learn: DynamoDB-Transaktionen

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

Zuletzt verifiziert am 2026-07-13 gegen die oben verlinkte offizielle AWS-Dokumentation.