# API Idempotency Request Retries

> Implement Idempotency-Key for safe POST retries: store request hash and response, handle in-flight 409, and combine with backoff. Use when payments, creates, or other costly side effects may be retried.

- Skill: `deangrant/api-idempotency-request-retries` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add deangrant/api-idempotency-request-retries`
- Raw SKILL.md: https://api.skillmd.com/api/skills/deangrant/api-idempotency-request-retries/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: deangrant (https://skillmd.com/u/deangrant)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/deangrant/api-idempotency-request-retries

---


# Idempotency and Request Retries

Use this skill when **POST/PATCH side effects** must survive client retries.

---

## 1. Protocol

Client sends `Idempotency-Key` (UUID). Server stores key → request hash +
response. Replays return the original response. Same key + different body →
**409**. In-flight duplicate → **409** (or wait policy documented).

---

## 2. Storage

TTL longer than max client retry window (often 24h). Redis/DB common. Include
tenant in the key namespace.

---

## 3. With retries

Clients retry with the **same** key after timeouts. Combine with backoff +
jitter. Never generate a new key on retry of the same logical operation.

---

## 4. Quick checklist

- [ ] Idempotency-Key on costly POSTs.
- [ ] Persist response for replay.
- [ ] Mismatch body → 409.
- [ ] Key scoped by tenant/client.
- [ ] TTL documented.

See [reference.md](reference.md) and [examples.md](examples.md).