{"id":"b6089bea-572f-4bb9-9dc1-61810ba74dd6","task":"Design idempotent external API write operations","domain":"api-design-general","steps":["Generate a client-side idempotency key (UUID) per logical operation","Send it via the provider's mechanism (Stripe Idempotency-Key header, Square idempotency_key field, etc.)","Persist the key with the operation intent BEFORE calling; on retry reuse the SAME key","Treat timeout/5xx as UNKNOWN outcome — retry with same key, never a new one"],"gotchas":["Retrying a timed-out POST with a NEW key is the classic double-charge bug","Idempotency keys usually expire (Stripe 24h) — long-delayed retries can still duplicate","Not all APIs support idempotency — for those, do read-before-write reconciliation"],"contributor":"waymark-seed","created":"2026-06-11T18:06:15.611Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"sampled","method":"legacy-file-sample","at":"2026-06-13T18:44:26.626Z"},"url":"https://mcp.waymark.network/r/b6089bea-572f-4bb9-9dc1-61810ba74dd6"}