Idempotent APIs in Node.js with Redis

Dima — Wed, 11 Feb 2026 01:28:00 +0000

Distributed systems lie.

Requests get retried. Webhooks arrive twice. Clients timeout and try again.
What should be a single operation suddenly runs multiple times — and now you’ve double-charged a customer or processed the same event five times.

Idempotency is the fix.
Doing it correctly is the hard part.

This post shows how to implement idempotent APIs in Node.js using Redis, and how the idempotency-redis package helps handle retries, payments, and webhooks safely.

What idempotency means for APIs

An API operation is idempotent if:

Multiple calls with the same idempotency key produce the same result — and side effects happen only once.

In practice:

One execution per idempotency key
Concurrent or retried requests replay the same result
Failures can be replayed too

This matters for:

💳 Payments
🔁 Automatic retries
🔔 Webhooks
🧵 Concurrent requests

Why naive solutions fail

Common approaches break down quickly:

In-memory locks → don’t work across instances
Database uniqueness → hard to replay results
Redis SETNX → no result or error replay
Returning 409 Conflict → pushes complexity to clients

What you actually need is coordination + caching + replay, shared across all nodes.

Using `idempotency-redis`

idempotency-redis provides idempotent execution backed by Redis:

One request executes the action
Others wait and replay the cached result
Errors are cached and replayed by default
Works across multiple Node.js instances

Basic example

import Redis from 'ioredis';
import { IdempotentExecutor } from 'idempotency-redis';

const redis = new Redis();
const executor = new IdempotentExecutor(redis);

await executor.run('payment-123', async () => {
  return chargeCustomer();
});

Call this five times concurrently with the same key — the function runs once.

Real-world use cases

Payments

Payment providers and clients retry aggressively.
Your API must never double-charge.

await executor.run(`payment:${paymentId}`, async () => {
  const charge = await stripe.charges.create(...);
  await saveToDB(charge);
  return charge;
});

If the response is lost, retries replay the cached result — no second charge.

Webhooks

Webhook providers explicitly say “events may be delivered more than once.”

await executor.run(`webhook:${event.id}`, async () => {
  await processWebhook(event);
});

Duplicate delivery? Same result. One execution.

Retries without fear

With idempotency in place, you can safely:

Enable HTTP retries
Retry background jobs
Handle slow or flaky dependencies

No duplicate work. No race conditions.

Error handling and control

By default, errors are cached and replayed — preventing infinite retries.

You can opt out selectively:

await executor.run(key, action, {
  shouldIgnoreError: (err) => err.retryable === true
});

When to use this

Use idempotency-redis if you:

Build APIs that mutate state
Accept retries or webhooks
Run multiple Node.js instances
Care about correctness under failure

Learn more

📦 npm: https://www.npmjs.com/package/idempotency-redis
🐙 GitHub: https://github.com/foreverest/idempotency-redis

If you’ve ever debugged a “why did this run twice?” incident — idempotency isn’t optional. It’s infrastructure.

Forem: Dima