liveBook · Manning

Idempotency key

As explained in Grokking Software Architecture

A request identifier that lets a payment processor recognize repeated submissions as the same transaction rather than separate transactions.

A payment request hits a network snag. Did the charge go through, or did it disappear? Retrying without a safety plan could charge the customer twice. An idempotency key is a request identifier that lets the payment processor recognize repeated submissions as the same transaction. section 6.4.2 section 10.2.2

The safety plan is simple:

  • Generate a unique key for the payment, typically a UUID, and send it with the request. section 6.4.2
  • Reuse that exact key on every retry. A fresh key on each attempt would give each attempt a different identity. section 10.2.2
  • Have the server check whether it has already processed a payment with that key. The payment processor can then recognize duplicates rather than treat them as new transactions. section 6.4.2 section 10.2.2

This matters for GraphQL mutations, which change data and are commonly sent over HTTP POST. Unlike REST methods such as PUT and DELETE, a mutation needs idempotency designed into its payload. A read-only GraphQL query does not change state just because it is repeated. section 6.4.2 section 6.12

Listing 6.3 GraphQL Mutation with Idempotency Key
# The Client sends the mutation with a unique key
mutation {
  processPayment(
    amount: 50.00, 
    idempotencyKey: "a1b2c3d4-e5f6-7890-1234-56789abcdef0"
  ) {
    status
    transactionId
  }
}

The payment mutation sends an idempotencyKey alongside the amount. A retry of this payment must keep the same key. section 6.4.2 section 10.2.2

A key is a safety measure, not a retry strategy by itself. A resilient payment service can also use timeouts, exponential backoff, and a fallback when retries run out. Those measures address different problems; the key helps keep the extra attempts from becoming extra charges. section 10.2.2 section 10.4.2

How Grokking Software Architecture covers it

How deep it goes
Explains key generation, reuse across retries, and a server database check, without specifying expiration or concurrency handling.
Examples
Illustrates a GraphQL payment mutation with a UUID and a resilient checkout service with retry and timeout handling.
What you can do after
Evaluate/understand how a shared key helps make payment retries safer.
How it connects
Connects idempotency with GraphQL mutations, HTTP methods, retries, and exponential backoff.

Also explained in

Compare how 4 books explain idempotency key →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Grokking Software Architecture. The section links point to the parts of the book it draws on.