Designing Idempotent Writes — Idempotency & Retry-Safe Systems

Design writes so repeats are harmless. Use state machines where transitions are guarded (paid → shipped only from paid); a repeated transition becomes a no-op or a clear 409. Use conditional writes (WHERE version = ?, If-Match) and upserts keyed by stable identifiers. Record processed operation IDs alongside side effects in the same transaction. Return the same result for a repeated request when possible so clients can proceed.

async def mark_shipped(db, order_id: str, shipment_id: str) -> Order:
    # Idempotent transition: repeating with the same shipment_id is a no-op
    row = await db.fetchrow(
        '''UPDATE orders SET status = 'shipped', shipment_id = $2
           WHERE id = $1 AND (status = 'paid' OR (status = 'shipped' AND shipment_id = $2))
           RETURNING *''', order_id, shipment_id)
    if row is None:
        raise Conflict(f"Order {order_id} cannot be shipped from its current state")
    return Order(**row)

export async function markShipped(orderId: string, shipmentId: string) {
  const { rows } = await pool.query(
    `UPDATE orders SET status = 'shipped', shipment_id = $2
     WHERE id = $1 AND (status = 'paid' OR (status = 'shipped' AND shipment_id = $2))
     RETURNING *`, [orderId, shipmentId]);
  if (rows.length === 0) throw new ConflictError(`Order ${orderId} cannot be shipped`);
  return rows[0];
}

@Modifying
@Query("""
    update Order o set o.status = 'SHIPPED', o.shipmentId = :shipmentId
    where o.id = :id and (o.status = 'PAID' or (o.status = 'SHIPPED' and o.shipmentId = :shipmentId))
    """)
int markShipped(String id, String shipmentId);   // 0 rows → 409 Conflict

Common pitfalls

Read-then-write checks without atomic conditions (races).
Returning errors for harmless repeats, causing client confusion.
Side effects (emails) triggered on every repeat of a transition.

Key points

Guarded state transitions
Atomic conditional writes and upserts
Repeat → same outcome

Common pitfalls

Key points

Practice questions