{
  "schema": "vedokrok.public-item.v1",
  "release_id": "MHC-RPUB-20260920-75ad787a",
  "url": "/knowledge/give-a-retryable-mutation-one-stable-operation-id",
  "id": "MHC-D-RESEARCH-0347",
  "version": "0.1.0",
  "title": "Give a retryable mutation one stable operation ID",
  "summary": "A retry should mean 'finish this operation,' not 'please create another one.'",
  "kind": "pattern",
  "body": "Attach a stable idempotency or request key to one logical mutation and reuse it for retries of that same intent. Generate a new key only for a genuinely new operation. Store enough context to recognize ambiguous responses and reconcile them. This is especially valuable for payments, job creation, provisioning and bulk actions where duplicates are expensive.",
  "limits": [
    "Do not assume idempotency exists where the service does not guarantee it, and do not reuse one key for materially different requests."
  ],
  "topics": [
    "union-safe-change-operations"
  ],
  "intents": [],
  "source_ids": [
    "RS-56B6FA675EBAA1EF"
  ],
  "evidence": [
    {
      "claim": "Amazon and Stripe document idempotency keys or request identifiers as a way to safely retry a mutation without unintentionally performing the same logical operation twice.",
      "source_id": "RS-56B6FA675EBAA1EF",
      "role": "supports",
      "note": "Idempotency semantics depend on the API contract and retention window; callers must not assume every endpoint supports them.",
      "locator": "Client request identifiers and retry safety"
    }
  ],
  "use_when": [
    "A create or update request may be retried after a timeout, dropped connection or transient service error."
  ],
  "avoid_when": [
    "Do not assume idempotency exists where the service does not guarantee it, and do not reuse one key for materially different requests."
  ],
  "example": "If a create-order call times out, retry with the same operation ID rather than issuing a second independent create request.",
  "check": "Repeated delivery of the same logical request cannot silently create multiple intended-once effects under the API contract.",
  "recognition": "A retry should mean 'finish this operation,' not 'please create another one.'",
  "sources": [
    {
      "id": "RS-56B6FA675EBAA1EF",
      "title": "Making retries safe with idempotent APIs",
      "url": "https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/"
    }
  ],
  "relations": [
    {
      "from": "MHC-D-RESEARCH-0347",
      "to": "MHC-D-RESEARCH-0349",
      "type": "useful_with",
      "url": "/knowledge/treat-a-timeout-as-an-unknown-outcome"
    }
  ],
  "collections": [
    {
      "id": "RC-4F77BDBBF2481574",
      "title": "Change live systems without turning one mistake into a large one",
      "url": "/collections/change-live-systems-without-turning-one-mistake-into-a-large-one"
    }
  ]
}