How I built a Go middleware for Stripe-style idempotency-key handling

Eben — Tue, 02 Jun 2026 20:22:00 +0000

Retries in payment and order APIs are a classic footgun. Your client times out, retries the request, and you've just charged someone twice. The fix is idempotency-key handling, but getting it right is harder than it looks.

The naive approach breaks under load

The obvious solution is Redis SETNX: claim a key before running the handler, release it after. Works fine on the happy path. Breaks in at least three ways:

Two identical requests arrive simultaneously before either has claimed the key. Both get through and execute.
Your handler panics or returns an error. The lock never gets released.
A client retries with a slightly different payload (a timestamp in the body, a different amount). You execute both and silently diverge.

Idempotency is one of those things that feels solved until you actually test it under concurrency.

What idempo does

idempo is a net/http middleware that implements the IETF Idempotency-Key draft with Stripe-compatible semantics. A client sends a unique Idempotency-Key header with a request. The middleware:

Claims the key atomically before the handler runs
If the key is new, runs the handler and stores the full response (status, headers, body)
If the same key arrives again, replays the stored response without running the handler, and adds Idempotency-Replayed: true so you know it happened
If the key is still in flight: 409 Conflict, same as Stripe
If the key is reused with a different payload: 422 Unprocessable Entity

Wiring it up

store := inmem.New(24*time.Hour, 5*time.Minute)
mw := idempo.New(store, idempo.Options{})

mux := http.NewServeMux()
mux.HandleFunc("POST /charge", chargeHandler)

http.ListenAndServe(":8080", mw.Handler(mux))
Because it's just func(http.Handler) http.Handler, it drops into any router:


// chi
r := chi.NewRouter()
r.Use(mw.Handler)

Pluggable backends

// In-memory (single instance or testing)
store := inmem.New(24*time.Hour, 5*time.Minute)

// Redis (distributed)
store := redis.New(&goredis.Options{Addr: "localhost:6379"}, 24*time.Hour, 5*time.Minute)

// Postgres (durable, ACID)
pg.RunMigration(connStr)
store, _ := pg.New(connStr, 24*time.Hour, 5*time.Minute)

Each backend enforces exactly-once execution at the storage layer: a mutex in memory, an atomic Lua script in Redis, and INSERT ... ON CONFLICT in Postgres.

The concurrency guarantee

The test suite fires 50 simultaneous identical requests and asserts the handler ran exactly once. The whole suite runs under -race in CI. If you've been burned by a race between SETNX and the actual handler execution, this is the part that matters.

One design decision worth calling out

When a duplicate arrives while the first request is still in flight, idempo returns 409 rather than blocking and waiting to replay. This matches Stripe's behavior.

My reasoning: holding connections open while waiting for an upstream to finish is a resource problem that compounds under load. Better to push the retry logic back to the client where it belongs. That said, if you need blocking behavior for your use case, the Store interface is just three methods (Claim, Complete, Abandon) and you can implement it yourself.

DEV Community: Eben