DynamoDB IdempotentParameterMismatchException

요약 — 지난 10분 내에 이미 사용된 ClientRequestToken으로 TransactWriteItems를 호출했지만 요청의 나머지가 바뀌었습니다. 토큰은 "이것은 같은 트랜잭션을 재시도한 것"이라고 약속하므로 — DynamoDB는 페이로드가 다른 토큰 재사용을 거부합니다. 바이트가 동일한 재시도에만 토큰을 재사용하고, 모든 새 논리적 트랜잭션에는 새 토큰(UUID)을 발급하세요.

무엇을 의미하나요

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를 멱등하게 만듭니다: 같은 토큰으로 여러 번 동일한 호출을 하면 단일 호출의 효과를 가지며, 타임아웃이 첫 시도가 착지했는지 숨길 때 트랜잭션을 이중 적용하는 것을 방지합니다. 토큰은 그것을 사용한 첫 요청이 완료된 후 10분 동안 유효합니다. 그 창 안에서 같은 토큰이지만 다른 파라미터로 요청이 도착하면, DynamoDB는 이를 재시도로 취급할 수 없고 — 새 트랜잭션으로 취급하는 것도 거부합니다. HTTP 400이며 그대로는 재시도할 수 없습니다.

왜 발생하나요

정적이거나 하드코딩된 토큰 — 모든 트랜잭션에 같은 토큰 문자열이 전송되어, 두 번째(다른) 트랜잭션이 첫 번째와 충돌합니다.
너무 거친 것에서 파생된 토큰 — 예: 사용자 ID나 테이블 이름, 그래서 같은 사용자에 대한 두 개의 다른 트랜잭션이 토큰을 공유합니다.
재시도가 요청을 다르게 재구성함 — 항목 안의 타임스탬프, TTL 값, 또는 생성된 ID가 첫 시도와 재시도 사이에 바뀌어, "같은" 트랜잭션이 더 이상 바이트 단위로 일치하지 않습니다.
두 코드 경로가 토큰 소스를 공유 — 같은 값으로 시드된 병렬 워커.

어떻게 고치나요

논리적 트랜잭션당 고유한 토큰을 생성하세요 — 트랜잭션이 구성되는 지점에서의 UUID:

import {randomUUID} from 'node:crypto';

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

재시도할 때 토큰을 요청과 함께 유지하세요 — 재구성된 것이 아니라 이미 만들어진 같은 요청 객체를 재시도해 페이로드의 어떤 것도 드리프트할 수 없도록 하세요. (AWS SDK는 자동 재시도를 위해 이를 올바르게 수행합니다. 버그는 거의 항상 요청을 재구성하는 애플리케이션 수준 재시도입니다.)
구성 전에 변동 값을 고정하세요 — 타임스탬프와 생성된 ID는 한 번 계산되어 재시도 시 재사용되어야 하며, 다시 평가되지 않아야 합니다.
멱등성을 기대하며 10분 후 토큰을 재사용하지 마세요 — 창이 지나면 요청이 완전히 새로운 것으로 취급되어 다시 적용됩니다.

DynoTable 데스크톱 앱은 트랜잭션이 건드린 정확한 항목을 검사하게 해주므로, "내 첫 시도가 실제로 착지했나?"가 추측이 아니라 조회가 됩니다.

References

공식 AWS 문서(위 링크)를 기준으로 2026-07-13에 마지막으로 검증되었습니다.

DynamoDB IdempotentParameterMismatchException

무엇을 의미하나요

왜 발생하나요

어떻게 고치나요

관련 오류

References