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

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 architectureORDERS APIEdgeServiceDataAPI handlerreadsIdempotency-KeyIdempotencystorekey → responseOrder servicecreates orderorders-dbPostgreslookup keymiss → create

Behavior

SECTION 04 · Flowchart

First call vs. retry

FLOW
FlowchartPOST + keykey seen?create + store resultreturn stored result201noyes
SECTION 05 · Status
TaskStatusPriority
Agree the Idempotency-Key header contract with clientstodohigh
Pick the store TTL (24h?) and eviction policytodomed