IETF Idempotency-Key HTTP Standard (RFC 9457 / Draft) & Financial Safety

--- description: IETF Idempotency-Key HTTP Standard (RFC 9457 / Draft) & Financial Safety - Production standard for idempotent mutation APIs (payments, transfers, orders). Enforces the IETF Idempotency-Key HTTP header specification, distributed atomic reservation locks in Redis (SETNX + TTL), in-flight collision 409 Conflict rejection, and exact cached response replay. globs: **/middleware/**/*.ts, **/payments/**/*.ts, **/orders/**/*.go alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ietf-idempotency-key-rfc-standard" --- # IETF Idempotency-Key HTTP Standard (RFC 9457 / Draft) & Financial Safety > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: AI processes payment and order mutations without idempotency keys, causing duplicate charges when network timeouts trigger client retries. ## System Constraints You are a Financial Systems and Idempotency Architecture Specialist. All state-mutating POST/PATCH HTTP endpoints handling payments, subscriptions, or asset modifications MUST enforce the IETF Idempotency-Key header. Implement atomic distributed locks, deduplicate in-flight requests, and replay responses with identical status codes. ## Strict Guidelines - Mandate presence of Idempotency-Key header on critical mutation endpoints; reject missing headers with 400 Bad Request. - Use atomic Redis SET key status EX 120 NX to claim an idempotency lock before executing any transaction. - If a concurrent request arrives while processing is in-flight, return HTTP 409 Conflict with Retry-After header. - Cache the final response status, headers, and body hash upon completion with a minimum 24-hour retention window. - Replay the exact previously cached HTTP response on duplicate keys, appending an Idempotent-Replayed: true header. ## Bad vs Good Implementations ### Atomic Idempotency Guard with Redis Distributed Locks in TypeScript #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Without an idempotency layer, network packet drops or browser page refreshes will execute multiple credit card charges against the customer, triggering payment disputes and severe compliance penalties. ```typescript // FATAL: Direct execution without idempotency protection app.post('/api/charges', async (req, res) => { // If network blips or mobile app retries 3 times, user is charged 3X! const charge = await paymentGateway.charge({ amount: req.body.amount, cardToken: req.body.cardToken }); res.json(charge); }); ``` #### Production Standard (Correct) > **Standard**: Implements the IETF Idempotency-Key standard using atomic Redis NX locks. Replays identical cached responses on duplicate retries and safely rejects concurrent in-flight requests with 409 Conflict. ```typescript import { Request, Response, NextFunction } from 'express'; import { redisClient } from '@/lib/redis'; export async function idempotencyMiddleware(req: Request, res: Response, next: NextFunction) { const idempotencyKey = req.header('Idempotency-Key'); if (!idempotencyKey) { return res.status(400).json({ error: 'Idempotency-Key header is required for this mutation' }); } const lockKey = `idemp:lock:${req.user.id}:${idempotencyKey}`; const responseKey = `idemp:resp:${req.user.id}:${idempotencyKey}`; // 1. Check if previously completed const cachedResponse = await redisClient.get(responseKey); if (cachedResponse) { const parsed = JSON.parse(cachedResponse); res.setHeader('Idempotent-Replayed', 'true'); return res.status(parsed.status).json(parsed.body); } // 2. Atomic distributed lock reservation (locks for 60 seconds) const acquired = await redisClient.set(lockKey, 'IN_FLIGHT', { NX: true, EX: 60 }); if (!acquired) { // Concurrently executing identical request return res.status(409).setHeader('Retry-After', '2').json({ error: 'A mutation with this Idempotency-Key is currently in-flight. Please retry shortly.' }); } // 3. Intercept response to store result const originalJson = res.json.bind(res); res.json = (body: any) => { redisClient.set(responseKey, JSON.stringify({ status: res.statusCode, body }), { EX: 86400 }); redisClient.del(lockKey); return originalJson(body); }; next(); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: IETF Idempotency-Key HTTP Standard (RFC 9457 / Draft) & Financial Safety

IETF Idempotency-Key HTTP Standard (RFC 9457 / Draft) & Financial Safety defines an industrial-grade behavioral standard for security engineering. Production standard for idempotent mutation APIs (payments, transfers, orders). Enforces the IETF Idempotency-Key HTTP header specification, distributed atomic reservation locks in Redis (SETNX + TTL), in-flight collision 409 Conflict rejection, and exact cached response replay. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: AI processes payment and order mutations without idempotency keys, causing duplicate charges when network timeouts trigger client retries. Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	AI processes payment and order mutations without idempotency keys, causing duplicate charges when network timeouts trigger client retries.	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Mandate presence of Idempotency-Key header on critical mutation endpoints

Mandate presence of Idempotency-Key header on critical mutation endpoints; reject missing headers with 400 Bad Request.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.