Why You Can Have Too Much Idempotency In Ledgers

The word “same” carries a lot of weight in a ledger.

It’s not that idempotency in ledgers is totally different from other software systems, no. Engineers who use libraries such as idemgotent or that Airbnb library we discussed a while ago are following standard patterns that work fine in most cases. These libraries work.

But they might not work in some cases.

I’m fond of saying that idempotency is a frustrating engineering problem because sufficiently stupid clients can bypass all of server’s idempotency checks. Most of these libraries are based on this idea: there’s an Idempotency-Key header generated and provided by the client, and it is the client’s responsibility to not regenerate the key for two requests that are meant to be “the same”. Other, more sophisticated ones rely on hashes built from the request payload, salted with the time the request is sent, in order to programatically determine uniqueness.

Both approaches, however, fail to consider situations in which “same” belongs in the context of the business. Their designs assume that idempotency is an engineering-only problem.

And in ledgers, it’s not.

I’m Alvaro Duran, and this is The Payments Engineer Playbook. You’re already subscribed to free newsletters that “teach” you how to get a job as a software engineer.

But you don’t want to get a job; you already have one. What you want is to learn how to be great at your job. Especially as a payments engineer, where stakes are sky-high, and the margin for error is razor-thin.

In The Payments Engineer Playbook, we investigate the technology that transfers money. All to help you become a smarter, more skillful, and more successful payments engineer. And we do that by cutting off one sliver of it and extracting tactics from it.

In today’s article, we’re looking at idempotency, sameness and retries in ledger systems. When it comes to money, idempotency isn’t about overloading the system, but actually preventing double charges and phantom payments. What “same” payment is gets determined, not as an engineering problem, but as something that the business gets to decide.

And that changes everything.