GraphQL mutations often trigger side effects such as database writes, emails, payment operations, messages, or external API calls.

This means mutation design must consider retries.

Suppose a client sends:

mutation {
  createPayment(input: $input) {
    id
  }
}

The server successfully creates the payment, but the network connection fails before the client receives the response. The client may retry.

If the mutation is not designed for retries, the same logical operation might happen twice.

A common solution is an idempotency key:

input CreatePaymentInput {
  amount: Float!
  currency: String!
  idempotencyKey: String!
}

The server stores or otherwise tracks the key and ensures repeated attempts for the same logical operation do not produce duplicate side effects.

Not every mutation needs strict idempotency. But operations involving payments, orders, provisioning, emails, or external side effects deserve careful retry semantics.

GraphQL itself does not automatically make mutations idempotent. Idempotency is an application and business design concern.