B2B Order API में Idempotency Keys 2026: UUIDv4 के साथ deep dive

Idempotency keys वह technique है जो किसी भी B2B API के POST request को retry-safe बनाती है। इसके बिना client पर हर network timeout एक "order बना या नहीं?" वाला question बन जाता है — और 30% cases में answer "दोनों बार" होता है। यह article Stripe से borrow किए production patterns को cover करता है जो FoxReload Orders API में apply हैं।

1. क्यों single retry दो orders बनाता है

Simple sequence: आपका ERP POST /v1/orders issue करता है payload {sku: "PSN_TR_50", qty: 1} के साथ। FoxReload order create करता है, delivery start करता है, पर TCP response खो जाती है (network blip)। आपका HTTP client 30s के बाद retry करता है — FoxReload नया request देखता है, दूसरा order बनाता है, balance दूसरी बार debit करता है। Result: duplicate।

Idempotency key के साथ यह scenario impossible है: server same key देखता है, original response return करता है, दूसरा order कभी create नहीं होता।

2. Client पर UUIDv4 generation

Key globally unique और unpredictable होनी चाहिए। UUIDv4 standard choice है:

import { randomUUID } from 'crypto';
import axios from 'axios';

async function createOrder(sku: string, qty: number) {
  const idempotencyKey = randomUUID(); // UUIDv4
  return axios.post('https://api.foxreload.com/v1/orders', {
    sku, qty, currency: 'USD',
  }, {
    headers: {
      'Authorization': `Bearer ${process.env.FOXRELOAD_KEY}`,
      'Idempotency-Key': idempotencyKey,
    },
    timeout: 30000,
  });
}

idempotencyKey को request issue करने से पहले अपने DB में persist करें। Retry पर वही key read करें — नई generate नहीं करें।

3. Server-side dedup window

FoxReload हर key को Redis में 24h TTL के साथ store करता है। Processing logic:

// server-side pseudocode
async function handleCreateOrder(key: string, payload: OrderPayload) {
  const existing = await redis.get(`idem:${key}`);
  if (existing) {
    const stored = JSON.parse(existing);
    if (hash(payload) !== stored.payloadHash) {
      return { status: 422, error: 'idempotency_conflict' };
    }
    return stored.response; // retry — original return करें
  }
  const response = await createOrderInternal(payload);
  await redis.set(`idem:${key}`, JSON.stringify({
    payloadHash: hash(payload),
    response,
  }), 'EX', 86400);
  return response;
}

Same key के साथ दो simultaneous requests की race Redis SETNX और idempotency_key पर Postgres advisory lock से resolve होती है।

4. Dedup storage backends की comparison

FoxReload 6-node Redis cluster run करता है, hash(idempotency_key) से sharded। यह dedup check पर <2ms p99 latency देता है।

CTA

Idempotency-Key FoxReload API के हर POST/PUT/DELETE endpoint पर support है। Full reference onboarding के बाद available है — access request करें।