DOCUMENTRFC-012

RFC — Idempotent order creation

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

Problem
01 · Hierarchy

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
RFC — Idempotent order creation2 / 6
Alternatives
02 · Options
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
RFC — Idempotent order creation3 / 6
Proposed design
03 · Architecture
SECTION 03 · Architecture

Idempotency layer

ARCH
Layered architectureORDERS APIEdgeServiceDataAPI handlerreadsIdempotency-KeyIdempotencystorekey → responseOrder servicecreates orderorders-dbPostgreslookup keymiss → create
RFC — Idempotent order creation4 / 6
Behavior
04 · Flowchart
SECTION 04 · Flowchart

First call vs. retry

FLOW
FlowchartPOST + keykey seen?create + store resultreturn stored result201noyes
RFC — Idempotent order creation5 / 6
Behavior
05 · Status
SECTION 05 · Status
TaskStatusPriority
Agree the Idempotency-Key header contract with clientstodohigh
Pick the store TTL (24h?) and eviction policytodomed
RFC — Idempotent order creation6 / 6
1 / 6
Document