idempotency_skill

Overview

This skill implements idempotency protection for mutation endpoints to ensure critical operations are safe to retry. It enforces Idempotency-Key handling, caches responses, and returns the same result for repeated requests. Use it to prevent duplicate charges, orders, inventory changes, and other non-idempotent side effects.

How this skill works

The skill requires an Idempotency-Key header and looks up a server-side record for that key and user before performing the mutation. If a cached record exists it returns the stored status and response. If not, it executes the operation, stores the response with status and expiration, and returns the result, ensuring at-most-once behavior across retries.

When to use it

• Payment processing endpoints (charges, refunds)
• Order creation and checkout flows
• Inventory updates, email sends, or other side-effectful mutations
• Whenever asked to “trust the frontend” to prevent duplicates
• Any mutation that must not happen more than once

Best practices

• Require an Idempotency-Key header and validate its presence on critical endpoints
• Scope keys to a user or logical owner to avoid cross-user collisions
• Cache both success and relevant error responses when appropriate, and expire records after a reasonable TTL
• Design client-side key generation: UUIDs for unique attempts or deterministic keys for retryable operations
• Log idempotent hits and provide metrics to detect frequent retries or misuse

Example use cases

• Charge creation endpoint that returns the same payment id for repeated requests with the same key
• Order API that stores and returns the original order response on retry instead of creating duplicates
• Inventory decrement endpoint that applies the change once and returns cached confirmation for retries
• Account creation guarded with a unique key plus database constraints to avoid duplicate accounts
• Email sending endpoint that caches send results to avoid duplicate deliveries