DOCUMENTRFC-012

RFC — Idempotent order creation

A proposal to make POST /orders safe to retry under network failure.

Problem

Clients retry POST /orders on timeouts, occasionally creating duplicate orders. We need creation to be safe to retry without double-charging.

SECTION 01 · Hierarchy

Why duplicates happen

MECE
Issue treeDuplicate ordersNetwork retriesClient timeout thenretryLB re-dispatchUser double-submitDouble-click
Legendquestionbranchtestable claim

Alternatives

SECTION 02 · Options
ADedup by cart hash
Reject if an identical cart exists recently.
  • No client change
  • False positives on real re-orders
REJECTED
BIdempotency key
Client sends a key; server stores the first result.
  • Exactly-once semantics
  • Standard pattern
  • Clients must send a key
CHOSEN

Proposed design

SECTION 03 · Architecture

Idempotency layer

ARCH
Layered architecture: 3 layers, 4 nodesORDERS APIEdgeServiceDataAPI handlerreadsIdempotency-KeyGATEWAYIdempotencystorekey → responseSVCOrder servicecreates orderSVCorders-dbPostgresDBlookup keymiss → create
LegendGATEWAYgatewaySVCserviceDBdatabasecallsentry point

Behavior

SECTION 04 · Flowchart

First call vs. retry

FLOW
Flowchart: 5 stepsPOST + keykey seen?create + storeresultreturn stored result201noyes
Legendstartstepdecision (diamond)nexterror pathhappy path
SECTION 05 · Status
TaskStatusPriority
Agree the Idempotency-Key header contract with clientstodohigh
Pick the store TTL (24h?) and eviction policytodomed