Idempotency Handling

This is a solid reference for preventing duplicate operations when requests get retried. Shows two approaches: Redis for simple caching and Postgres for more robust tracking with status management. The database pattern is what you want for payments or orders where you need to handle concurrent requests trying to process the same idempotency key. Includes the crucial detail of hashing request bodies to catch key reuse with different payloads. The cleanup job examples are helpful since expired keys will bloat your table if you ignore them. Good practical code you can actually drop into an Express app or payment handler without much modification.

skills.sh installs: 415
GitHub stars: 248
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add secondsky/claude-skills --skill idempotency-handling --agent claude-code

Installs into .claude/skills of the current project.

Files

Idempotency Handling

Ensure operations produce identical results regardless of execution count.

Idempotency Key Pattern

const redis = require('redis');
const client = redis.createClient();

async function idempotencyMiddleware(req, res, next) {
  const key = req.headers['idempotency-key'];
  if (!key) return next();

  const cached = await client.get(`idempotency:${key}`);
  if (cached) {
    const { status, body } = JSON.parse(cached);
    return res.status(status).json(body);
  }

  // Store original send
  const originalSend = res.json.bind(res);
  res.json = async (body) => {
    await client.setEx(
      `idempotency:${key}`,
      86400, // 24 hours
      JSON.stringify({ status: res.statusCode, body })
    );
    return originalSend(body);
  };

  next();
}

Database-Backed Idempotency

CREATE TABLE idempotency_keys (
  key VARCHAR(255) PRIMARY KEY,
  request_hash VARCHAR(64) NOT NULL,
  response JSONB,
  status VARCHAR(20) DEFAULT 'processing',
  created_at TIMESTAMP DEFAULT NOW(),
  expires_at TIMESTAMP DEFAULT NOW() + INTERVAL '24 hours'
);

CREATE INDEX idx_idempotency_expires ON idempotency_keys(expires_at);

SKILL.md on GitHub