Idempotency Handling Skill

Idempotency Handling

Overview
When to Use
Quick Start
Reference Guides
Best Practices

Overview

Implement idempotency to ensure operations produce the same result regardless of how many times they're executed.

When to Use

Payment processing
API endpoints with retries
Webhooks and callbacks
Message queue consumers
Distributed transactions
Bank transfers
Order creation
Email sending
Resource creation

Quick Start

Minimal working example:

import express from "express";
import Redis from "ioredis";
import crypto from "crypto";

interface IdempotentRequest {
  key: string;
  status: "processing" | "completed" | "failed";
  response?: any;
  error?: string;
  createdAt: number;
  completedAt?: number;
}

class IdempotencyService {
  private redis: Redis;
  private ttl = 86400; // 24 hours

  constructor(redisUrl: string) {
    this.redis = new Redis(redisUrl);
  }

  async getRequest(key: string): Promise<IdempotentRequest | null> {
    const data = await this.redis.get(`idempotency:${key}`);
    return data ? JSON.parse(data) : null;
  }
// ... (see reference guides for full implementation)

Reference Guides

Detailed implementations in the references/ directory:

| Guide | Contents | |---|---| | Express Idempotency Middleware | Express Idempotency Middleware | | Database-Based Idempotency | Database-Based Idempotency | | Stripe-Style Idempotency | Stripe-Style Idempotency | | Message Queue Idempotency | Message Queue Idempotency |

Best Practices

✅ DO

Require idempotency keys for mutations
Store request and response together
Set appropriate TTL for idempotency records
Validate request body matches stored request
Handle concurrent requests gracefully
Return same response for duplicate requests
Clean up old idempotency records
Use database constraints for atomicity

❌ DON'T

Apply idempotency to GET requests
Store idempotency data forever
Skip validation of request body
Use non-unique idempotency keys
Process same request concurrently
Change response for duplicate requests

Agent Skills: Idempotency Handling

Install this agent skill to your local

Skill Files