Send the same idempotency key when you retry a write

How to do it

A timeout does not tell you whether the provider did the work. Without a key, a retry can ship a parcel twice or send two invoices. Make the key from your own record, such as the order ID and the step, or store a random one before the first try. Send it in the header the provider documents, often Idempotency-Key. If the provider has no key, look up the result before a retry. Retry only as retry with backoff and jitter and cap retries across the whole service say. Card charges follow create each charge with an idempotency key.

Examples

JavaScript example

async function bookShipmentOnce(order) {
  const key = `shipment-${order.id}`;
  return withRetries(() => fetch(`${CARRIER_URL}/v2/shipments`, {
    method: 'POST',
    headers: { 'idempotency-key': key, authorization: `Bearer ${CARRIER_KEY}` },
    body: JSON.stringify({ reference: order.id }),
    signal: AbortSignal.timeout(CARRIER_TIMEOUT_MS),
  }));
}

Python example

def book_shipment_once(order) -> httpx.Response:
    key = f"shipment-{order.id}"
    return with_retries(lambda: httpx.post(
        f"{CARRIER_URL}/v2/shipments",
        json={"reference": order.id},
        headers={"Idempotency-Key": key, "Authorization": f"Bearer {CARRIER_KEY}"},
        timeout=CARRIER_TIMEOUT,
    ))

How to check

Make the provider's fake do the work and then time out on the first call. The adapter retries with the same key, and the fake holds one shipment.

Sources

• Expired IETF draft on the Idempotency-Key HTTP Header Field

Related rules

• Retry with backoff and jitter in API design
• Cap retries across the whole service in Operations
• Create each charge with an idempotency key in Payments