DynamoDB IdempotentParameterMismatchException

TL;DR — Anda memanggil TransactWriteItems dengan ClientRequestToken yang sudah digunakan dalam 10 menit terakhir, tetapi sisa permintaan berubah. Token menjanjikan "ini transaksi yang sama, dicoba ulang" — jadi DynamoDB menolak penggunaan ulang token yang payload-nya berbeda. Gunakan ulang token hanya untuk retry yang byte-identik; buat token baru (UUID) untuk setiap transaksi logis baru.

Apa artinya

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

# what the engine actually returns, reproduced against Amazon DynamoDB (live service, us-east-1):
IdempotentParameterMismatchException: Specified idempotent token was used with different request parameters within the idempotency window

ClientRequestToken membuat TransactWriteItems idempoten: beberapa panggilan identik dengan token yang sama memiliki efek satu panggilan, yang melindungi Anda dari menerapkan transaksi dua kali ketika timeout menyembunyikan apakah upaya pertama mendarat. Token tetap valid selama 10 menit setelah permintaan pertama yang menggunakannya selesai. Jika permintaan tiba dalam jendela itu dengan token yang sama tetapi parameter berbeda, DynamoDB tidak dapat memperlakukannya sebagai retry — dan menolak memperlakukannya sebagai transaksi baru juga. HTTP 400, tidak dapat dicoba ulang apa adanya.

Mengapa itu terjadi

• Token statis atau di-hard-code — string token yang sama dikirim untuk setiap transaksi, jadi transaksi kedua (berbeda) bertabrakan dengan yang pertama.
• Token diturunkan dari sesuatu yang terlalu kasar — mis. ID pengguna atau nama tabel, jadi dua transaksi berbeda untuk pengguna yang sama berbagi token.
• Retry membangun ulang permintaan secara berbeda — timestamp, nilai TTL, atau ID yang dihasilkan di dalam item berubah antara upaya satu dan retry, jadi transaksi "sama" tidak lagi cocok byte-per-byte.
• Dua jalur kode berbagi sumber token — worker paralel yang di-seed dengan nilai yang sama.

Bagaimana cara memperbaikinya

1. Hasilkan token unik per transaksi logis — UUID pada titik di mana transaksi disusun:

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

   SalinDisalin

2. Jaga token bersama permintaan saat mencoba ulang — coba lagi objek permintaan yang sudah dibangun yang sama, bukan yang dibangun ulang, agar tidak ada di payload yang dapat menyimpang. (AWS SDK melakukan ini dengan benar untuk retry otomatisnya; bug-nya hampir selalu retry tingkat aplikasi yang menyusun ulang permintaan.)

3. Pin nilai volatil sebelum menyusun — timestamp dan ID yang dihasilkan harus dihitung sekali dan digunakan ulang pada retry, bukan dievaluasi ulang.

4. Jangan gunakan ulang token setelah 10 menit mengharapkan idempotensi — melewati jendela permintaan diperlakukan sebagai benar-benar baru dan akan diterapkan lagi.

Aplikasi desktop DynoTable memungkinkan Anda memeriksa item persis yang disentuh transaksi, yang membuat "apakah upaya pertama saya benar-benar mendarat?" menjadi pencarian alih-alih tebakan.

Kesalahan terkait

• TransactionCanceledException — transaksi berjalan dan digulung balik.
• TransactionConflictException — transaksi bersamaan menyentuh item yang sama.
• TransactWriteItems: terlalu banyak item
• Contoh kode: TransactWriteItems in Node.js — menunjukkan penggunaan ClientRequestToken.
• Pelajari: DynamoDB transactions

Referensi

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

Terakhir diverifikasi 2026-07-13 terhadap dokumentasi resmi AWS yang ditautkan di atas.