DEV Community: Rasikh

The provider timed out after committing

Rasikh — Sat, 29 Aug 2026 07:05:24 +0000

Your HTTP client raises ETIMEDOUT on POST /charges. Something has to be written to the database, the status column has two useful values, and so the catch block writes failed.

The timeout isn't the bug. Timeouts are normal and you'll get another one this week. The bug is that failed is a claim about the outside world, and at the moment you write it you are not in a position to make any claim at all. The provider may have taken the money 200 ms ago. You have asserted, in durable storage, that it didn't.

Everything downstream now believes you. The customer gets an error and pays again. Support issues a refund for a charge your system says never happened. Reconciliation, six hours later, finds a movement on their side with nothing on yours and files it as a break, which is the only part of the system that behaved correctly.

Three outcomes, one symptom

A request that doesn't come back has three possible histories, and they are indistinguishable from where you're standing:

What happened	What you saw
The request never reached them	Timeout
It reached them, they committed, the response was lost	Timeout
It reached them, they committed, your process died before writing	Timeout

There's a fourth that's worth separating out, because it breaks the mental model people fall back on. The provider accepted and committed, and the underlying rail rejects it forty minutes later. That one isn't ambiguous, it's just slow, and it means "confirmed" is itself a state with a subsequent transition rather than an end.

The standard error handler collapses all of this into a boolean. try succeeded, catch failed. That shape is fine when the failure costs you a retry and nothing else. It is wrong the moment the operation moves money, because in this domain the third outcome is not an exception case. During the incidents where processes are dying and connections are being reset, which is exactly when you most need to be right, it's the common case.

The correction is small to state and awkward to retrofit: unknown is a state your system holds, not an error it handles.

`provider_ref IS NULL` is not a state machine

Most systems already encode the unknown accidentally. There's a payments row with status = 'failed' and a null provider_ref, and someone on the team knows that a null there sometimes means "we never got a response" and sometimes means "we never made the call". That knowledge lives in one person and expires when they change teams.

The distinction has to be in the enum, because the enum is what queries filter on and dashboards group by.

create type payment_state as enum (
  'intended',      -- we have decided to pay, nothing has been sent
  'in_flight',     -- a request is on the wire right now
  'unknown',       -- the request ended without an answer
  'confirmed',     -- the provider has told us it happened
  'settled',       -- it appeared in a statement we ingested
  'rejected'       -- the provider has told us it did not happen
);

Two things about that list are load-bearing.

unknown and rejected are different states, and only one of them is a fact. rejected means the provider gave you an answer. unknown means nobody has. Merging them is precisely the mistake that started this post.

And confirmed is not the last state. The provider saying yes over an API is their intent, not the money's arrival. Only settled is backed by a statement, which is the part reconciliation exists to establish. A system that stops at confirmed has substituted a promise for the evidence.

Write the intent down before you make the call

The dangerous window isn't the call. It's the gap between deciding to pay and recording that you decided.

// Broken. A crash on line 1 leaves no trace that money may be moving.
const charge = await provider.charge(amount, card);
await db.payments.insert({ providerRef: charge.id, state: "confirmed" });

If the process dies inside provider.charge, there is no row. Nothing to reconcile, nothing to poll, nothing to alert on. The money left and your database has never heard of it. This is worse than a wrong state, because a wrong state at least shows up in a query.

Commit the intent first, then call:

const payment = await db.payments.insert({
  state: "intended",
  amount,
  idempotencyKey: key,          // generated here, stored here, reused forever
  reference: ourReference,      // the join key reconciliation will need
  expectedResolutionBy: addBusinessHours(now, 2),
});

await db.payments.setState(payment.id, "in_flight");

try {
  const charge = await provider.charge(amount, card, { idempotencyKey: key });
  await db.payments.confirm(payment.id, charge.id);
} catch (err) {
  await db.payments.setState(payment.id, classify(err));
}

This is write-ahead logging with the business as the log. The row exists before the side effect, so every crash leaves something behind that knows to go and ask.

Note what classify is allowed to return. A response that says no is rejected. A connection that was refused before any bytes left the machine is rejected too, because the request provably never arrived. Everything else, including every read timeout, is unknown. If you can't tell which kind of timeout you got, it's unknown. Guessing in the safe direction here costs you a poll; guessing in the other direction costs you a duplicate payment.

The idempotency key belongs on that row for the same reason. It's a property of the intent, not of the attempt, which is the contract the retry depends on.

Unknown needs a deadline and an owner

A state that nothing is responsible for leaving is just a slower way of losing data. unknown is only useful if something is obliged to resolve it, and the obligation has to be written into the row rather than into a runbook.

That's what expected_resolution_by is for. It gives you two queries that a human can act on:

-- Working as designed: young unknowns, being polled.
select count(*) from payments
 where state = 'unknown' and expected_resolution_by > now();

-- The alert. Something is stuck and a person needs to look.
select * from payments
 where state = 'unknown' and expected_resolution_by < now()
 order by created_at;

Alert on the age of the oldest unknown, not on the count. Volume tracks traffic and provider health, and it's noisy in a way that trains people to ignore it. Age tracks whether resolution is working at all. Fifty unknowns that all clear within four minutes is a healthy system on a bad network. One unknown from Tuesday is an outstanding question about real money, and it will still be there in March unless someone is told.

The pressure you have to resist is organisational, not technical. A queue of unknowns is uncomfortable to look at, and somebody will propose a nightly job that ages them out to failed so the dashboard goes green. That job converts an open question into a false answer, which is the only genuinely irreversible operation in this whole design.

Ask, but know which answer is authoritative

There are three ways an unknown resolves, and they differ in latency and in how much you should believe them.

Query the provider by your own key. Fastest, and available on demand. Most payment APIs let you look up by idempotency key or by your reference; the ones that only let you look up by their ID are useless here, because their ID is exactly what you didn't receive. This is the check you run on a backoff schedule.

Wait for a webhook. Free and quick when it works, and it is not a plan on its own. Webhooks are at-least-once at best, they arrive out of order, and they get dropped by your own load balancer during the incident that caused the unknowns in the first place. Treat an inbound webhook as a hint that makes you poll, not as the source of truth.

The webhook race is worth naming, because it produces a bug that looks impossible. Their event can arrive before your own transaction commits. Your handler looks up the payment, finds nothing, logs "unknown webhook" and drops it. The confirmation you needed most is the one you threw away. Persist unmatched webhooks in their own table, keyed by the reference they carry, and re-match them when the payment appears.

Read the settlement file. Slowest, usually a day, and the only one of the three that constitutes evidence. The API says what the provider believes. The statement says what the bank did. When those two disagree, and they do, the statement wins.

So the polling loop is a convenience that closes most unknowns in minutes, and the file is the backstop that closes the rest. Build both. A system with only the poll has no answer when the provider's API is the thing that's broken.

Money in flight is a balance

Here's the part that turns this from an engineering pattern into something the finance team can use: an unknown isn't only a row state, it's an amount, and that amount has to be somewhere in the ledger.

The usual instinct is to write no entries until the payment confirms. That keeps the ledger clean and makes it lie: the customer's money has left their account and, according to your books, has not gone anywhere. Double entry has an answer for this that predates all of us, which is a suspense account.

On intent:      DR Customer               100.00
                CR Payments in transit    100.00

On confirmation: DR Payments in transit   100.00
                 CR Provider clearing     100.00

On rejection:    DR Payments in transit   100.00
                 CR Customer              100.00

Every leg is a new entry rather than an edit, so the history of an unknown that eventually resolved is still readable a year later. That's the same append-only discipline reconciliation depends on.

What you get for it is a number: the balance of "payments in transit" is your total exposure to unresolved outcomes, in currency, at any instant. Graph it. It should be small and it should spike and drain. A balance that only grows means resolution has quietly stopped working, and you'll see that on a chart weeks before anyone opens the payments table.

It also gives the unknown a home in the accounts. Nobody has to invent a policy for it during a close, because it was already a line item.

Cancelling an unknown is another unknown

The tempting shortcut, when you have a payment you're unsure about, is to void it and start clean.

You can't. POST /charges/void needs the charge ID you never received, and the variants keyed on your reference have the identical failure mode: their response can time out too. Now you have an unknown cancellation of an unknown payment, and the state space has squared rather than shrunk.

Unknowns resolve by asking, not by acting. The only safe operations while you're in that state are reads. Once you know a charge exists, refunding it is a normal, well-defined thing with its own record, and a refund is a new fact rather than an erasure of the old one.

This is also why the answer to "should we retry?" is no, not until you've asked. Retrying a read timeout is safe if and only if the idempotency key travels with it and the provider still recognises it. Both halves have to hold. Their key window is often shorter than the age of your oldest unknown, and once it lapses, your retry is a brand new charge as far as they're concerned.

Your timeout is a policy, not a network fact

The number of unknowns you have to handle is partly your own choice, made in a config file, usually by accident.

If your client's read timeout is 10 seconds and the provider's p99 is 14, you are manufacturing unknowns at roughly one percent of traffic, deterministically, forever. Every one of those requests is going to succeed on their side. You just decided not to wait for the news. Look up the number, don't assume it: the ones the provider publishes are for the happy path, and card authorisations that route through 3-D Secure or a slow issuer are not the happy path.

Two adjustments follow. Set the read timeout above the provider's real tail latency, and give the write path its own timeout budget rather than inheriting the API gateway's. And separate the two timeouts in your client configuration, because connect and read mean genuinely different things here: a connection you never established is a request that never happened, and a response you never read is a question.

Then check what your infrastructure does underneath you. A 30 second idle timeout on a load balancer, a proxy that retries idempotent methods on its own, a client library that quietly retries once by default: any of those turns a clean request into an ambiguous one without appearing in your code. The library default is the one that catches people, because it's a retry you didn't write and therefore didn't attach a key to.

What the customer sees

None of this reaches the user as "unknown". They get three states, and the middle one is the whole point of the exercise:

Processing. Honest, and the correct answer for as long as you're unsure. Give it an expected duration so it doesn't read as a hang.
Confirmed, once you have an answer you'd defend in a dispute.
Failed, only when the provider said no.

The thing you have to stop is the customer resolving the ambiguity for you by pressing Pay again. Their second attempt is a genuinely different request with a different key, and idempotency will process it exactly as instructed. What stops it is a business uniqueness constraint: one non-terminal payment per invoice, enforced in the database, not in the button's disabled attribute.

create unique index one_open_payment_per_invoice
    on payments (invoice_id)
 where state in ('intended', 'in_flight', 'unknown');

That partial index is about fifteen minutes of work and it removes the most common way an unknown becomes a duplicate charge: an anxious human with a working mouse.

What this doesn't buy you

Not fewer unknowns. The count is set by network reality and your timeout policy. This makes them visible, bounded and resolvable, which is the whole available win.
Not idempotency. Modelling the state doesn't make the retry safe. The key does, and it has to have been on the row before the first attempt.
Not reconciliation. Polling closes an unknown against the provider's opinion. Only the statement closes it against the bank's.
Not correctness. A payment can be fully confirmed, fully settled, perfectly reconciled and still the wrong amount to the wrong person. Nothing here has an opinion about intent.
Not a resolution guarantee. Some unknowns need a human and a phone call. The design's job is to make sure there are three of those a quarter and that each one is found in hours, not that the number reaches zero.

The short version

A timeout is not a failure. Writing failed on one is a claim you can't support.
unknown belongs in the enum, next to rejected and distinct from it.
Commit the intent, with its key and its reference, before the call that can vanish.
Only a connection that was never established counts as "never happened". Every read timeout is unknown.
Give every unknown a resolution deadline, and alert on the age of the oldest, never the count.
Poll by your own key. Treat webhooks as hints, and store the ones that arrive before the payment exists.
The settlement file is the only authority. The API is an opinion, however confident.
Put money in flight in a suspense account, so the exposure is a balance somebody can graph.
Never cancel an unknown. Reads only, until you know.
One open payment per invoice, as a partial unique index, or the customer will resolve the ambiguity for you.

Two things to go and look at today. Grep your codebase for catch blocks around a provider call and read what each one writes to the database; every status = 'failed' on a timeout is a future refund request for a charge you'll swear never happened. Then find your client's read timeout and put it next to the provider's p99 latency. If the first number is smaller, you already know how many unknowns you're creating a day, and you've never seen a single one of them.

Originally published at mashhadi.me.

Idempotency is not a key, it's a contract

Rasikh — Sun, 23 Aug 2026 05:35:45 +0000

Every payments API has an Idempotency-Key header. Far fewer have written down what it means, and the ones that haven't are usually running a SELECT … WHERE key = ? before the insert and calling the job done.

A key is a token. A contract is a set of answers: what counts as the same request, how long the answer stays valid, what a caller gets when their retry lands while the first attempt is still running, and which failures are worth remembering. Skip those and you've made double charges rarer without making them impossible, which is the worst outcome available: now nobody is watching for them.

The promise is "same outcome", not "skip the duplicate"

HTTP already has idempotent methods. RFC 9110 defines PUT and DELETE that way: sending the request twice leaves the server in the same state as sending it once. POST is deliberately excluded, which is why the header exists at all. It's a way to bolt the property onto the one method that doesn't have it.

Notice what the definition covers and what it doesn't. It constrains server state. It says nothing about what the caller sees, and the caller is the entire reason you're doing this. Here's the handler people write first:

const seen = await db.keys.find(key);
if (seen) return res.status(200).json({ status: "ok" });

State is protected. The client is not. They retried because they never saw the first response: the socket died, the load balancer timed out, the phone lost signal in a lift. What they need back is the charge id from attempt one. What they got is {"status":"ok"}, which tells them a charge exists somewhere with an id they will never learn.

So the promise has two halves, and both matter:

The work happens at most once.
Every retry gets back the original response, with the same status and the same body, byte for byte.

The second half is what turns your endpoint into something a client can safely retry in a loop. Without it, retries are safe for you and useless for them.

What counts as "the same request"

The key is not the identity of the request. It's a name the client picked for one. The identity is the key plus what was in the body.

POST /payments   Idempotency-Key: 7f3a…   { "amount": 5000, "to": "acct_1" }
POST /payments   Idempotency-Key: 7f3a…   { "amount": 9000, "to": "acct_1" }

Replay the first response and you've silently refused to send $90 while telling the caller you sent it. Execute the second and the key bought you nothing. Neither is acceptable, which means there's only one correct answer: reject it. Store a fingerprint of the request alongside the key and compare on every hit.

import { createHash } from "node:crypto";

/** Stable hash of the parts of a request that change what it *does*. */
function fingerprint(path: string, body: unknown): Buffer {
  return createHash("sha256").update(path).update("\0").update(canonicalJson(body)).digest();
}

Stripe returns a 400 with an idempotency_error here. 422 is defensible too. What isn't defensible is picking one of the two bodies and proceeding.

The trap in this section is canonicalJson. Fingerprint the raw bytes and you'll ship false rejections, because a retry is very often a re-serialisation, not a replay of the same buffer. Two things reliably bite:

Key order. A client that builds the payload from a hash map may emit fields in a different order the second time. Same request, different bytes.
Timestamps. A client_ts or requested_at field filled in with Date.now() at send time changes on every attempt. Now every retry is a fingerprint mismatch and your safest clients get the most errors.

Canonicalise (sort keys, normalise numbers), or fingerprint an explicit allowlist of the fields that carry meaning. Both work. Hashing the whole body verbatim does not.

The race is the actual problem

Check-then-insert is a time-of-check-to-time-of-use bug wearing a business shirt. Two retries arrive 4 ms apart, both SELECT and miss, both charge. This is not an exotic interleaving; it's the normal shape of a retry storm, because whatever made the client retry (a timeout) also tends to make it retry more than once.

Let the database arbitrate. Insert first, on the way in.

create table idempotency_keys (
  account_id      uuid        not null,
  endpoint        text        not null,
  key             text        not null,
  fingerprint     bytea       not null,
  state           text        not null
                  check (state in ('in_flight', 'succeeded', 'failed')),
  response_status int,
  response_body   jsonb,
  resource_id     uuid,
  locked_until    timestamptz,
  created_at      timestamptz not null default now(),
  primary key (account_id, endpoint, key)
);

const claimed = await db.query(
  `insert into idempotency_keys (account_id, endpoint, key, fingerprint, state, locked_until)
   values ($1, $2, $3, $4, 'in_flight', now() + interval '60 seconds')
   on conflict (account_id, endpoint, key) do nothing
   returning key`,
  [accountId, endpoint, key, fp],
);

if (claimed.rowCount === 1) {
  // We own this key. Do the work, then write the response back.
}

Zero rows means someone else owns it, and the existing row tells you what to do:

Stored state	What the caller gets
Fingerprint differs	`400`: same key, different request
`succeeded`	The stored status and body, replayed
`failed`, deterministic	The stored status and body, replayed
`in_flight`, lock live	`409` + `Retry-After`
`in_flight`, lock expired	Recovery. See below; do not just re-run it

The 409 is worth defending, because the tempting alternative is to block: wait on a row lock until the first attempt finishes, then return its response. It reads beautifully and it's a bad idea at load. Every waiter is a held connection, so a provider that's gone slow converts directly into pool exhaustion, and the requests you're holding are by definition from clients that already gave up once. Hand back 409 with a Retry-After and let the client's backoff do the waiting. It has a much better place to do it than your connection pool.

The key has to outlive the process that made it

Server-generated keys don't work. Fetching one is itself a network call that can time out, and now you need idempotency for your idempotency endpoint. So the client owns the key, and where the client stores it decides whether any of this functions.

// Broken: a new key on every attempt. This is a plain retry loop with extra steps.
for (const delay of backoff) {
  await post("/payments", body, { key: crypto.randomUUID() });
}

// Also broken: survives the loop, not a crash. The retry after restart is a new key.
const key = crypto.randomUUID();

The key belongs next to the intent, in whatever durable thing already represents "we mean to pay this": the row in your own database, the payload in the job queue. Generate it once, when the intent is created, and read it back on every attempt including the ones that happen after a deploy, a pod eviction, or somebody replaying a dead-letter queue by hand on Monday morning.

The idempotency key is a property of the job, not of the attempt. If you take one line from this post, take that one. Most idempotency that fails in production fails here, in the client, in code nobody thought of as payment code.

Scope it, or you'll replay someone else's response

Make the key composite: (account_id, endpoint, key). Global uniqueness on the key column alone has two failure modes, and one of them is a security incident.

Two endpoints sharing a key namespace means a client that reuses order-8812 for both /payments and /refunds gets the payment response back from the refund call. Annoying.

Two tenants sharing a namespace is worse. Keys are frequently derived from things that aren't secret (an order number, an invoice id, a checkout-2026-08-12-0001), so tenant B can arrive with a key tenant A already used and receive A's stored response body. You built a cross-tenant read out of a deduplication table. Scope by account and the whole class disappears.

The window is a promise about time, and 24 hours is usually a guess

Stripe expires keys after 24 hours. That's a reasonable default for a browser and a bad fit for a lot of what actually retries.

Think about the longest path a retry of your endpoint can take. A queue with seven-day retention. An operator replaying Friday's failures when they get in on Monday. A mobile client that was in a tunnel, then a plane, then a country with roaming disabled. If your window is 24 hours and your job queue retries for 7 days, then on day two the same key is a new key and the retry is a fresh charge, with the idempotency system fully installed, monitored, and reporting green.

The window must be at least as long as the longest retry horizon of any caller you have. When you can't bound that, split the record instead of expiring it:

The response body is the expensive part. JSONB of a full resource, times every write request. Expire that on the usual timescale.
The key, fingerprint and resource_id are 100 bytes. Keep them for a year.

A retry that arrives after the body is gone but while the key survives is still recognisable. Return 409 and point at resource_id. "You already did this, it's payment pay_…, go look" is an unhelpful answer that leaves the caller with a lookup to do. It's also infinitely better than charging them again, which is the only other option once you've forgotten the key entirely.

Idempotency is not atomicity

This is the part that separates a key column from a system that works.

const charge = await provider.charge(amount, card);   // ← crash here
await ledger.record(charge.id, amount);

The process dies between those two lines. The provider has taken the money. Your ledger doesn't know. The key row says in_flight and will say so until the lock expires. The key prevented a duplicate request; it did nothing about partial work, because it was never the kind of thing that could.

An expired in_flight lock is an unknown, not a failure. That distinction is the whole game. Treat it as a failure and re-run the handler and you have built a double-charge machine whose trigger is your own worst outage: the one where processes were dying mid-request. Two things make the recovery path safe, and you want both:

Push your key downstream. Derive the provider's idempotency key deterministically from yours, so a re-run is also a re-run to them:

const providerKey = createHash("sha256").update(key).update(":provider:v1").digest("hex");

Now re-running the handler after a crash is safe at the boundary that matters, because the provider recognises the second call as the same one. The :v1 is there so you can roll the derivation without every historical key changing meaning.

Reconcile before you retry. On finding an expired lock, ask the provider what happened to providerKey before doing anything else. If they have a charge, adopt it, write the ledger row you owe, and mark the key succeeded. Only when they've never heard of it do you execute.

Skipping the reconciliation step and relying purely on the downstream key mostly works, right up until the downstream key window is shorter than yours. Now you know to check that number.

Don't cache failures you'd want retried

The last decision the contract owes an answer to: when the work fails, does the key remember?

It depends entirely on whether re-running would fail the same way.

Deterministic failures (schema validation, a hard decline, an unknown account) get stored and replayed. Re-running produces the identical error and costs you a provider call to learn it.
Transient failures (provider 503, a socket timeout, a serialisation conflict, a pod OOM) release the key. Set it back to unclaimed, or clear the lock so the next attempt with the same key claims it cleanly.

Get this backwards and you build a trap. Seal the key as failed on a 500 and the client's retry, using the same key, doing exactly what your docs told them to do, receives a permanent 500. Their only way out is a new key, which is precisely the double charge the header existed to prevent. You'd have been safer with no idempotency at all, because then at least the retry would have worked.

The rule fits on one line: cache a failure if and only if re-running it would produce the same failure.

What the contract actually says

If your API documentation can't answer these, you don't have idempotency. You have a column.

Who generates the key, and what should it be derived from?
What's the scope: per account, per endpoint, or both?
How long does a key live, and what happens on the first request after that?
What defines "same request", and what's returned when the key matches but the body doesn't?
What comes back while the first attempt is still running?
Which failures are remembered and which are retryable?
Is a replayed response marked as one? (An Idempotent-Replay: true header costs nothing and makes client-side debugging dramatically less miserable.)

Seven answers. Publish them and callers can write a retry loop with confidence. Leave them implicit and every integrator discovers your semantics through an incident.

What this doesn't buy you

Four honest limits:

Not ordering. Idempotent isn't commutative. A retried update and a retried cancel can still land in either order, and each one being safe on its own says nothing about the pair.
Not exactly-once. There's no exactly-once delivery over a network; the FLP result and every practical system agree. What you get is at-least-once delivery plus an idempotent receiver, which adds up to effectively-once. That's the real ceiling and it's enough.
Not double-submit protection. A user hammering Pay twice sends two different keys for two genuinely distinct requests, and idempotency will faithfully process both. That's a business uniqueness constraint (one pending payment per invoice), enforced somewhere else entirely.
Not correctness. Every one of these mechanisms protects a duplicate. None of them notices that the amount was wrong, the account was wrong, or the rate was stale.

The short version

Return the original response, not a bare acknowledgement. Retries need the resource id.
Fingerprint the request. Same key with a different body is an error, never a coin flip.
Insert first and let a unique constraint settle the race. Check-then-insert loses.
Answer in-flight requests with 409 and Retry-After. Don't block on a lock.
The client generates the key, and stores it with the intent, not inside the retry loop.
Scope keys per account and per endpoint. Global keys leak responses across tenants.
Size the window against your slowest retry path, and keep the key long after you drop the body.
An expired in-flight record means unknown. Reconcile before re-running.
Pass a derived key downstream so a re-run is a retry all the way through.
Remember deterministic failures. Release transient ones.

A concrete place to start: search your codebase for a SELECT on an idempotency table that runs before the corresponding INSERT. Every one of those is a double charge waiting for a slow afternoon, and the fix is a unique constraint and about twenty lines. Then go and read your queue's maximum retention, and compare it against your key expiry. Those two numbers disagree far more often than anyone expects.

Originally published at mashhadi.me.

Money as a data type

Rasikh — Thu, 20 Aug 2026 14:35:30 +0000

Most guides open with 0.1 + 0.2 === 0.30000000000000004 and conclude "don't use floats for money." True, and not very useful. The interesting question is what you replace it with, because "use decimals" and "use integers" are different answers that fail in different places. Neither of them addresses the bug most likely to reach production: a function that cheerfully adds 500 US dollars to 500 Japanese yen and returns 1000 of nothing.

Money isn't a number. It's a number, a currency, a scale, and a rounding policy, and if your type only carries the first one the other three end up scattered across call sites as assumptions.

Floats lose money in ways that survive your tests

The accumulation bug is the famous one:

let balance = 0;
for (let i = 0; i < 10; i++) balance += 0.1;

balance === 1; // false
balance; // 0.9999999999999999

This one is easy to catch, because the result looks obviously wrong the moment you print it. Here's the version that doesn't:

Math.round(1.005 * 100) / 100; // 1

Not 1.01. The nearest double to 1.005 is 1.00499999999999989342, so multiplying by 100 gives 100.49999999999999, and rounding that down is arithmetically correct. Round-to-nearest-cent is the single operation you would never think to unit test, and it is wrong for a value a human typed into a form.

There's also a ceiling. Doubles represent integers exactly only up to Number.MAX_SAFE_INTEGER, which is 9007199254740991. In cents that's about 90 trillion dollars, so you're fine, right up until someone stores an amount in a currency with a smaller unit or you accumulate a notional across a whole book.

Decimals fix the arithmetic, not the model

Swap in decimal.js, Java's BigDecimal, or Postgres NUMERIC and 1.005 is exactly 1.005. Every arithmetic complaint above goes away.

What doesn't go away:

new Decimal("500").plus(new Decimal("500")); // 1000

One thousand what? A Decimal carries no currency, no scale policy, and no rounding mode. You've fixed the representation and kept the hole in the type, and in my experience essentially every expensive money bug lives in that hole rather than in the third decimal place.

Store minor units, and make the exponent data

Store amounts as integer minor units (cents, satang, fils) in a BigInt. It's exact, there's no rounding at rest, and you're not near any ceiling.

The trap is what people write next:

const display = amount / 100; // wrong for a third of the world

ISO 4217 assigns every currency an exponent, and it is not always 2:

Currency	Exponent	1234567 minor units
JPY	0	¥1,234,567
USD	2	$12,345.67
KWD	3	1,234.567
CLF	4	123.4567

Zero-decimal currencies include JPY, KRW and VND. Three-decimal currencies include KWD, BHD, OMR, JOD and TND. So the exponent is a lookup, never a literal:

const EXPONENT: Record<Currency, number> = { USD: 2, JPY: 0, KWD: 3 };

function toDecimalString(m: Money): string {
  const e = EXPONENT[m.currency];
  const negative = m.minor < 0n;
  const digits = (negative ? -m.minor : m.minor).toString().padStart(e + 1, "0");
  const whole = digits.slice(0, digits.length - e);
  const frac = e === 0 ? "" : "." + digits.slice(digits.length - e);
  return `${negative ? "-" : ""}${whole}${frac}`;
}

For display, hand that string straight to Intl.NumberFormat. Its format() accepts a string, not just a number, which means you can render an exact value without round-tripping it through a double:

const fmt = new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" });
fmt.format(toDecimalString({ minor: 123456n, currency: "USD" })); // "$1,234.56"

Intl already knows each currency's exponent, so ¥1,234 renders without a decimal point and KWD 1,234.567 renders with three, for free.

Rounding is a policy decision, not a default

Round half away from zero (what most people mean by "round") is biased. Every tie goes the same direction, so the error accumulates instead of cancelling:

values     0.5   1.5   2.5   3.5   4.5      sum
exact                                       12.5
half-up      1     2     3     4     5      15
half-even    0     2     2     4     4      12

Half-even, also called banker's rounding, sends ties to the nearest even integer. Half of them go up, half go down, and across a large book the drift is far smaller. It's also the IEEE-754 default.

Half-even is not automatically the right answer. Tax authorities, card scheme rules and loan regulations sometimes specify a mode, and it isn't always the unbiased one. The point is that the mode is a decision that belongs in a signature:

function convert(from: Money, rate: Rate, mode: RoundingMode): Money;

not a default buried three layers down in a formatting helper.

Splitting a bill is where naive money types die

Divide $10 three ways. Each share is $3.33, and three of those is $9.99. You have lost a cent, and if the other side of that entry is a real bank transfer, your ledger no longer balances.

Division isn't the operation you want. Allocation is: hand out every minor unit, distribute the remainder deterministically, guarantee the parts sum to the whole.

export function allocate(total: bigint, ratios: bigint[]): bigint[] {
  const sum = ratios.reduce((a, r) => a + r, 0n);
  if (sum <= 0n) throw new RangeError("ratios must sum to a positive value");

  let remainder = total;
  const shares = ratios.map((r) => {
    const share = (total * r) / sum; // BigInt division truncates toward zero
    remainder -= share;
    return share;
  });

  // Hand the leftover units out one at a time, in order.
  const step = total < 0n ? -1n : 1n;
  for (let i = 0; remainder !== 0n; i = (i + 1) % shares.length, remainder -= step) {
    shares[i] += step;
  }

  return shares;
}

allocate(1000n, [1n, 1n, 1n]); // [334n, 333n, 333n]
allocate(500n, [3n, 7n]); // [150n, 350n]
allocate(100n, [1n, 1n, 1n, 1n, 1n, 1n, 1n]); // [15n, 15n, 14n, 14n, 14n, 14n, 14n]

That step variable exists because of a bug I wrote on the way to this post. My first version incremented by 1n unconditionally, which is correct for payments and quietly wrong for refunds: allocate(-1000n, [1n, 1n, 1n]) returned three shares of -333n, summing to -999n. A missing cent, on exactly the code path where a customer is getting money back.

This is also the reason the ordering is worth thinking about. Handing the remainder to the first participants every time is deterministic, which is what you want for reproducibility, but it isn't fair over repeated splits. If the same three accounts split odd amounts every month, rotate the starting index by something stable. An invoice number works.

The currency belongs in the type

Make the currency part of the static type and cross-currency arithmetic stops compiling:

type Currency = "USD" | "JPY" | "KWD";

type Money<C extends Currency = Currency> = {
  readonly minor: bigint;
  readonly currency: C;
};

const add = <C extends Currency>(a: Money<C>, b: Money<C>): Money<C> => ({
  minor: a.minor + b.minor,
  currency: a.currency,
});

add({ minor: 500n, currency: "USD" }, { minor: 500n, currency: "JPY" });
//                                     ^ Type '"JPY"' is not assignable to type '"USD"'

Types are erased at runtime, though, and money arrives over HTTP from systems that have never heard of your union. So keep the runtime guard as well:

if (a.currency !== b.currency) {
  throw new TypeError(`Cannot add ${a.currency} to ${b.currency}`);
}

Conversion is then a separate operation with a different shape. It is not multiplication by a number. It consumes a rate that knows where it came from, and it returns money in a different currency:

type Rate<F extends Currency, T extends Currency> = {
  from: F;
  to: T;
  value: string; // exact decimal, not a float
  quotedAt: string; // ISO 8601
  source: string; // which provider, which feed
};

function convert<F extends Currency, T extends Currency>(
  amount: Money<F>,
  rate: Rate<F, T>,
  mode: RoundingMode,
): Money<T>;

Persist the rate you actually used alongside the resulting entry. Six months later, someone reconciling a break needs to know whether the discrepancy is a bug or a rate that moved between quote and capture, and "we looked it up at the time" is not an answer.

JSON is a float in a trench coat

You can do all of the above and give it away at the boundary:

JSON.parse('{"amount": 9007199254740993}').amount; // 9007199254740992

The JSON spec doesn't bound numeric precision, but JSON.parse in every JavaScript runtime produces a double. Any consumer written in JS silently truncates whatever you sent.

Two wire formats survive the trip. Integer minor units, which is what Stripe does: "amount": 2000 means $20.00, with a published list of zero-decimal currencies so clients know how to interpret it. Or a decimal string, "amount": "12.34", which is self-describing but needs an exact parser on the other end.

One sharp edge if you go the BigInt route:

JSON.stringify({ amount: 1n });
// TypeError: Do not know how to serialize a BigInt

You need an explicit encoder. That's a feature. It forces the wire representation to be a decision someone made rather than whatever your ORM happened to emit.

What to put in the database

In Postgres, BIGINT minor units plus a currency column, or NUMERIC(19, 4). Both are exact. Pick based on whether you need sub-minor-unit precision, not on which one looks tidier.

Don't use the money type. Its fractional precision comes from lc_monetary, a server setting, so the same column can mean different things on two machines and a dump/restore across locales can change your values. The Postgres documentation itself steers you elsewhere.

Whatever you choose, the currency column travels with the amount, in the same table, non-null. A bare amount column is the same bug as a bare number, just durable. Constrain it against a currencies table that also carries the exponent, so there's exactly one place in the system that knows JPY has none.

Where this model stops working

Minor units are a settlement precision, and plenty of finance happens at a finer grain. Interest accrual, per-unit pricing, and FX rates all need more digits than the currency has. The fix isn't to abandon the model, it's to keep two scales explicitly: compute at high precision, round once at the point money actually moves, and store both the unrounded and the settled figure so the rounding is auditable.

Three more honest limits:

BigInt is meaningfully slower than number. Irrelevant in a request handler, possibly relevant inside a risk-scoring loop that runs a million times a second. Measure before you care.
Type-level currency only works if the currency set is closed at compile time. If yours is loaded from config, you're back to runtime checks, and the static version is a comfortable illusion.
None of this catches a wrong rate, a wrong sign, or a posting to the wrong ledger account. It makes an entire class of representation errors impossible. It does not make you correct.

Test the invariants, not the examples

Money types are unusually well suited to property-based testing, because the rules are short and absolute:

allocate always sums back to the total, for every total and every set of ratios
equal ratios never produce shares differing by more than one minor unit
parse(format(m)) round-trips to m
addition is commutative and associative within a currency
addition across currencies always throws

Those are five properties covering more ground than a page of hand-picked examples. The first one is what caught the refund bug earlier in this post; I ran it across roughly 23,000 generated combinations of totals and ratios, and the negative case failed immediately. No example-based test I would have thought to write covers allocate(-1000n, [1n, 1n, 1n]).

The short version

Never a float or double for a monetary amount, anywhere in the stack.
Store integer minor units or an exact decimal.
Look the exponent up per currency. It is not always 2.
Put the currency inside the type, and reject cross-currency arithmetic loudly.
Make the rounding mode a parameter, not a default.
Allocate; don't divide.
Cross the wire as minor units or a decimal string, never as a JSON number.
Test invariants, not examples.

If you want a concrete place to start: grep your codebase for / 100 and * 100. Every hit is either a hardcoded currency assumption or a float round-trip, and usually both. It's an afternoon of work, and it's the highest-value refactor most financial codebases have sitting in front of them.

Originally published at mashhadi.me.

DEV Community: Rasikh

The provider timed out after committing

Three outcomes, one symptom

provider_ref IS NULL is not a state machine

Write the intent down before you make the call

Unknown needs a deadline and an owner

Ask, but know which answer is authoritative

Money in flight is a balance

Cancelling an unknown is another unknown

Your timeout is a policy, not a network fact

What the customer sees

What this doesn't buy you

The short version

Idempotency is not a key, it's a contract

The promise is "same outcome", not "skip the duplicate"

What counts as "the same request"

The race is the actual problem

The key has to outlive the process that made it

Scope it, or you'll replay someone else's response

The window is a promise about time, and 24 hours is usually a guess

Idempotency is not atomicity

Don't cache failures you'd want retried

What the contract actually says

What this doesn't buy you

The short version

Money as a data type

Floats lose money in ways that survive your tests

Decimals fix the arithmetic, not the model

Store minor units, and make the exponent data

Rounding is a policy decision, not a default

Splitting a bill is where naive money types die

The currency belongs in the type

JSON is a float in a trench coat

What to put in the database

Where this model stops working

Test the invariants, not the examples

The short version

`provider_ref IS NULL` is not a state machine