DynamoDB IdempotentParameterMismatchException

TL;DR — TransactWriteItems'ı, son 10 dakikada zaten kullanılmış bir ClientRequestToken ile çağırdınız ama isteğin geri kalanı değişti. Belirteç "bu, yeniden denenmiş aynı işlemdir" sözünü verir — bu yüzden DynamoDB, yükü farklı olan bir belirteç yeniden kullanımını reddeder. Belirteci yalnızca bayt bakımından aynı yeniden denemeler için yeniden kullanın; her yeni mantıksal işlem için yeni bir belirteç (bir UUID) üretin.

Ne anlama gelir

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

ClientRequestToken, TransactWriteItems'ı idempotent yapar: aynı belirteçle yapılan birden çok özdeş çağrı, tek bir çağrının etkisine sahiptir, ki bu, bir zaman aşımı ilk denemenin ulaşıp ulaşmadığını gizlediğinde bir işlemi iki kez uygulamaktan sizi korur. Bir belirteç, onu kullanan ilk istek tamamlandıktan sonra 10 dakika geçerli kalır. Bu pencere içinde aynı belirteçle ama farklı parametrelerle bir istek gelirse, DynamoDB onu bir yeniden deneme olarak ele alamaz — ve onu yeni bir işlem olarak da ele almayı reddeder. HTTP 400, olduğu gibi yeniden denenebilir değil.

Neden olur

• Statik ya da sabit kodlanmış bir belirteç — her işlem için aynı belirteç dizesi gönderilir, bu yüzden ikinci (farklı) işlem ilkiyle çakışır.
• Çok kaba bir şeyden türetilen belirteç — örneğin kullanıcı kimliği ya da tablo adı, dolayısıyla aynı kullanıcı için iki farklı işlem bir belirteci paylaşır.
• Yeniden deneme, isteği farklı yeniden oluşturdu — bir öğe içindeki bir zaman damgası, TTL değeri ya da üretilmiş bir kimlik, birinci deneme ile yeniden deneme arasında değişti, dolayısıyla "aynı" işlem artık bayt-bayt eşleşmiyor.
• İki kod yolu bir belirteç kaynağını paylaşıyor — aynı değerle tohumlanmış paralel işçiler.

Nasıl düzeltilir

1. Mantıksal işlem başına benzersiz bir belirteç üretin — işlemin oluşturulduğu noktada bir UUID:

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

2. Yeniden denerken belirteci istekle birlikte tutun — yeniden oluşturulmuş bir isteği değil, zaten oluşturulmuş aynı istek nesnesini yeniden deneyin, böylece yükte hiçbir şey kayamaz. (AWS SDK'ları bunu otomatik yeniden denemeleri için doğru yapar; hata neredeyse her zaman isteği yeniden oluşturan uygulama düzeyinde bir yeniden denemedir.)

3. Oluşturmadan önce değişken değerleri sabitleyin — zaman damgaları ve üretilmiş kimlikler bir kez hesaplanmalı ve yeniden denemede yeniden kullanılmalı, yeniden değerlendirilmemelidir.

4. 10 dakikadan sonra idempotentlik bekleyerek bir belirteci yeniden kullanmayın — pencerenin ötesinde istek yepyeni olarak ele alınır ve tekrar uygulanır.

DynoTable masaüstü uygulaması, bir işlemin dokunduğu tam öğeleri incelemenize olanak tanır, ki bu "ilk denemem gerçekten ulaştı mı?" sorusunu bir tahmin değil, bir arama yapar.

İlgili hatalar

• TransactionCanceledException — işlem çalıştı ve geri alındı.
• TransactionConflictException — eşzamanlı bir işlem aynı öğeye dokundu.
• TransactWriteItems: too many items
• Kod örneği: TransactWriteItems in Node.js — ClientRequestToken kullanımını gösterir.
• Öğrenin: 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

En son 2026-07-13 tarihinde yukarıda bağlantısı verilen resmi AWS belgelerine karşı doğrulandı.