IdempotentParameterMismatch

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

1. 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.
2. 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.
3. 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

1. 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.
2. 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.
3. 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.
4. 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.

# 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 params

import { 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 token

How 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

Related Errors

Decision Support

Official References

• -AWS EC2 - Ensuring idempotency with client tokens
• -AWS CloudFormation - Client request tokens
• -AWS Builders Library - Making retries safe with idempotent APIs
• -AWS Official Documentation