Idempotency keys
Plug-and-play skills and prompts for every AI coding agent
npx -y skills add Amey-Thakur/AI-SKILLS --skill idempotency-keysAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- 18 days oldThe repository was created 18 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
- 4 stars4 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Implement idempotency keys so retried requests produce one effect and one canonical response. Use when making POST endpoints retry-safe, especially payments and order creation.
SKILL.md
2.4 KB, as published. Nobody here has run it
Idempotency keys
A retry after a network timeout must not charge the card twice. The client names the operation with a key; the server ensures one execution and replays one recorded response.
Method
- Client generates, server scopes. Client sends
Idempotency-Key: <uuid>per logical operation (same key on retry, new key for a genuinely new attempt). Server scopes stored keys by authenticated caller and endpoint so keys cannot collide across tenants or routes. - Reserve the key atomically before doing work. Insert
(key, scope, request_hash, status=in_progress)with a unique constraint in the same database as your business data. Lost race = key exists: this is the whole mechanism; check-then-insert without the constraint is a duplicate generator under load. - Bind the key to the request body. Store a hash of the payload; same key + different hash returns 422. Otherwise a client bug replays order A's response to order B's request.
- Record the outcome, replay it verbatim. On completion, store
status code and response body against the key; any later duplicate
gets exactly that response with an
Idempotent-Replay: trueheader. Concurrent duplicate while in_progress: 409 with Retry-After, do not run the work twice in parallel. - Choose the failure policy explicitly. Recommended: store the error response for deterministic failures (validation) but clear the key on infrastructure failures so a retry can succeed. Document which you do; clients build their retry loops on it.
- Expire pragmatically. 24-72h TTL covers real retry windows; sweep expired rows. An unbounded key table is a slow-motion outage.
Boundaries
- GET/PUT/DELETE are idempotent by contract already; keys are for POST and other effectful non-idempotent operations.
- The key dedupes the request; it does not make your downstream calls safe. Inside the execution you still need transactional effects (see transactional-outbox).
- If the operation's effect happens outside your database (external charge API), execute it via that provider's own idempotency mechanism and store their reference before acking yours.