IdempotentParameterMismatch
AWS IdempotentParameterMismatch means a request was submitted with a client token that was previously used for a different operation with different parameters. The idempotency token is already associated with a prior request whose parameters do not match the current request.
Last reviewed: March 28, 2026|Editorial standard: source-backed technical guidance
What Does Idempotent Parameter Mismatch Mean?
Idempotency tokens are meant to allow safe retries of the same request. If you retry with the same token and same parameters, AWS returns the original result. But if you reuse a token with different parameters, AWS cannot determine whether this is a retry or a new conflicting request, so it rejects it with IdempotentParameterMismatch. The token is permanently bound to the first request that used it.
Common Causes
- -Client generates idempotency tokens based on a non-unique value such as a timestamp with low resolution or a user ID, so two different operations executed close together share the same token and the second receives IdempotentParameterMismatch.
- -Retry logic reuses a token from a previous request but the parameters have changed between attempts, for example a price or quantity field was updated between the original request and the retry.
- -CloudFormation stack creation is retried with the same client request token but a modified template. The token is bound to the original template parameters and rejects the modified request.
How to Fix Idempotent Parameter Mismatch
- 1Generate a new unique idempotency token using UUID v4 for the current request. Never derive tokens from low-cardinality values like timestamps, user IDs, or sequential counters.
- 2Verify that retry logic preserves the original token and original parameters together. If either the token or the parameters need to change, treat the request as a new operation with a fresh token.
- 3For CloudFormation, generate a new client request token when resubmitting a modified template rather than reusing the token from the previous attempt.
Step-by-Step Diagnosis for Idempotent Parameter Mismatch
- 1Identify the idempotency token that triggered the error and find the original request it was first used with. Compare the original parameters against the current request parameters to confirm they differ.
- 2Review the token generation logic to determine whether it can produce duplicate values. Check for timestamp-based tokens, sequential IDs, or other low-cardinality sources.
- 3Audit retry logic to confirm it preserves both the original token and the original parameters when retrying. Verify that no parameters are recalculated or updated between the original request and the retry.
- 4Check whether the token namespace is shared across different operation types. Tokens used for one type of operation should not be reused for a different operation type even if the intent is similar.
Token Generation and Uniqueness
- -Audit all idempotency token generation code and replace any non-UUID sources. Timestamps are dangerous because two requests within the same millisecond can produce identical tokens, and user IDs or sequential counters can collide across different operations (example: token generated as userId + Date.now() collides when two requests from the same user fire within 1ms of each other).
- -Confirm tokens are scoped to a single operation attempt and never reused. Store the generated token alongside the request parameters before sending, and on retry use the stored token-parameter pair rather than generating a new token (example: generate token T1 for request R1, store {token: T1, params: R1}, retry uses stored T1 with stored R1).
Retry Logic Parameter Immutability
- -Freeze all request parameters at the time the idempotency token is generated. Any parameter that changes between the original request and a retry creates a mismatch that triggers IdempotentParameterMismatch (example: an order retry that recalculates the total price due to a currency fluctuation between attempts will fail if the recalculated price differs from the original).
- -For operations where parameters may legitimately change between attempts such as price updates or inventory adjustments, treat each parameter change as a new operation with a new token rather than a retry of the original. Generate a fresh UUID and send the new parameters as an independent request.
Implementation Examples
# Generate UUID token for idempotent EC2 launch
CLIENT_TOKEN=$(python3 -c "import uuid; print(uuid.uuid4())")
# Use same token for retries - same token + same params = safe retry
aws ec2 run-instances \
--image-id ami-12345678 \
--instance-type t3.micro \
--count 1 \
--client-token $CLIENT_TOKEN
# Store CLIENT_TOKEN with request params before sending
# On retry: use stored CLIENT_TOKEN with original unmodified paramsimport { randomUUID } from 'crypto';
import { EC2Client, RunInstancesCommand } from '@aws-sdk/client-ec2';
const client = new EC2Client({ region: 'us-east-1' });
function createLaunchRequest(imageId, instanceType) {
return {
token: randomUUID(),
params: {
ImageId: imageId,
InstanceType: instanceType,
MinCount: 1,
MaxCount: 1,
},
};
}
async function launchWithRetry(request, maxRetries = 3) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
try {
return await client.send(new RunInstancesCommand({
...request.params,
ClientToken: request.token,
}));
} catch (err) {
if (err.name === 'IdempotentParameterMismatch') {
throw new Error('Token reused with different params - generate new request');
}
if (attempt < maxRetries - 1) continue;
throw err;
}
}
}import boto3
import uuid
client = boto3.client('cloudformation', region_name='us-east-1')
def create_stack(stack_name, template_body):
client_token = str(uuid.uuid4())
params = {
'StackName': stack_name,
'TemplateBody': template_body,
'ClientRequestToken': client_token,
}
try:
response = client.create_stack(**params)
return response
except client.exceptions.AlreadyExistsException:
return client.describe_stacks(StackName=stack_name)
# Never reuse client_token with a modified template_body
# If template changes, call create_stack again with a new tokenHow to Verify the Fix
- -Generate a new UUID token for the current request and confirm the operation succeeds without IdempotentParameterMismatch.
- -Verify the token generation logic produces globally unique values by running it in parallel and confirming no collisions occur.
- -Test the retry flow end to end. Confirm that retrying with the same token and same parameters succeeds and returns the original result, while retrying with the same token and different parameters correctly fails with IdempotentParameterMismatch.
How to Prevent Recurrence
- -Standardize idempotency token generation across all services using UUID v4 from a cryptographically secure random source and document this as the required approach in API client guidelines.
- -Store generated tokens alongside their associated request parameters in a durable store before sending. This enables correct retry behavior and prevents accidental token reuse with modified parameters.
- -Add token uniqueness assertions to integration tests that generate tokens in parallel and verify no collisions occur under concurrent load.
Pro Tip
- -treat the idempotency token as a content hash of the operation intent rather than a random identifier. Hash the combination of operation type, resource identifier, and immutable parameters so the same logical operation always produces the same token while any parameter change automatically produces a different token.
Decision Support
Compare Guide
409 Conflict vs 412 Precondition Failed: When to Use Each
Choose 412 when If-Match or If-Unmodified-Since checks fail; choose 409 for state conflicts without failed precondition headers during concurrent updates.
Playbook
Conflict and Concurrency Playbook (409 / 412 / OptimisticLock)
Use this playbook to separate true write conflicts from stale precondition failures, then apply safe re-fetch, optimistic-lock, and retry choices.
Official References
Provider Context
This guidance is specific to AWS services. Always validate implementation details against official provider documentation before deploying to production.