メニュー
Design idempotent APIs that handle duplicate requests safely. Outputs idempotency key strategy, deduplication storage design, response caching patterns, and client retry guidance.
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。
npx skills add https://github.com/kalilurrahman/kr-claudiator-skills --skill idempotent-apiコマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
SOC 職業分類に基づく
SKILL.md を表示中
| name | idempotent-api |
| description | Design idempotent APIs that handle duplicate requests safely. Outputs idempotency key strategy, deduplication storage design, response caching patterns, and client retry guidance. |
| argument-hint | ["API type","expected retry rate","storage backend","consistency requirements"] |
| allowed-tools | Read, Write |
An idempotent operation produces the same result whether executed once or many times. HTTP GET, PUT, and DELETE are naturally idempotent. POST is not — but can be made so with idempotency keys. This matters because networks fail, clients retry, and without idempotency, retries create duplicate charges, double sends, and data corruption.
fastapi FastAPI, Header, HTTPException, Depends
typing
redis.asyncio redis
json
hashlib
datetime datetime
app = FastAPI()
r = redis.Redis(host=, port=, decode_responses=)
IDEMPOTENCY_TTL =
() -> []:
idempotency_key:
():
scoped_key:
cached = r.get(scoped_key)
cached:
stored = json.loads(cached)
fastapi.responses JSONResponse
JSONResponse(
status_code=stored[],
content=stored[],
headers={: },
)
order = order_service.create(request)
response_body = {: order., : order.status}
scoped_key:
r.setex(
scoped_key,
IDEMPOTENCY_TTL,
json.dumps({: , : response_body}),
)
response_body
():
scoped_key:
cached = r.get(scoped_key)
cached:
json.loads(cached)[]
order = order_service.get(order_id)
order order.customer_id != user_id:
HTTPException()
order.status == :
result = {: order_id, : , : }
order.status == :
order = order_service.confirm(order_id)
result = {: order_id, : }
:
HTTPException(, )
scoped_key:
r.setex(scoped_key, IDEMPOTENCY_TTL, json.dumps({: result}))
result
-- For financial operations where Redis TTL is insufficient
CREATE TABLE idempotency_records (
key VARCHAR(255) PRIMARY KEY, -- user_id:idempotency_key
response JSONB NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
expires_at TIMESTAMPTZ NOT NULL
);
CREATE INDEX ON idempotency_records (expires_at);
-- Cleanup job: DELETE FROM idempotency_records WHERE expires_at < NOW();
async def get_or_create_idempotent(key: str, fn, ttl_days: int = 7):
"""Database-backed idempotency for financial operations."""
existing = await db.fetchone(
"SELECT response FROM idempotency_records WHERE key = $1 AND expires_at > NOW()",
[key]
)
if existing:
return json.loads(existing["response"]), True # (result, was_replayed)
result = await fn() # Execute the operation
await db.execute(
"""INSERT INTO idempotency_records (key, response, expires_at)
VALUES ($1, $2, NOW() + INTERVAL '$3 days')
ON CONFLICT (key) DO NOTHING""",
[key, json.dumps(result), ttl_days]
)
return result, False
# Client SDK — how to use idempotency keys correctly
import uuid
import httpx
import time
class APIClient:
def create_order(self, order_data: dict, max_retries: int = 3) -> dict:
# Generate once per logical operation — NOT per retry
idempotency_key = str(uuid.uuid4())
for attempt in range(max_retries):
try:
response = httpx.post(
"/api/v1/orders",
json=order_data,
headers={"Idempotency-Key": idempotency_key},
timeout=10.0,
)
if response.status_code in [200, 201]:
return response.json()
if response.status_code == 422:
raise ValidationError(response.json())
# 5xx — retry with same key
if response.status_code >= 500:
time.sleep(2 ** attempt)
continue
except httpx.TimeoutException:
# Network timeout — safe to retry with same key
time.sleep(2 ** attempt)
continue
raise Exception("Max retries exceeded")
## Idempotency Keys
POST endpoints that create resources or trigger operations support idempotency
via the `Idempotency-Key` header.
**When to use:** Any operation you might need to retry — order creation, payments,
refunds, email sends.
**How to use:**
1. Generate a unique UUID for each distinct operation: `uuid4()`
2. Include it as `Idempotency-Key: <uuid>` in the request header
3. On retry (timeout, network error, 5xx), send the SAME key
4. The server returns the original response — the operation runs only once
**Key validity:** 24 hours from first use
**Response on replay:** Same response body + `Idempotency-Replayed: true` header
**What not to do:**
- Don't generate a new key on each retry — this defeats the purpose
- Don't reuse keys across different operations
- Don't use the same key for different users
| Anti-Pattern | Problem | Fix |
|---|---|---|
| New key per retry | Each retry creates a new record | Generate key before first attempt; reuse on all retries |
| Global key namespace | User A can see User B's responses | Scope key to user: {user_id}:{client_key} |
| Idempotency for GETs | GETs are already idempotent | Only POST, PATCH for non-idempotent operations |
| No TTL on keys | Storage grows forever | 24-hour TTL for standard ops; 7 days for financial |
| Re-executing on cache miss | Race condition: two identical requests both execute | Atomic check-and-set on first request |
Idempotency-Replayed: true header tells clients the response is from cache.