Principle: Idempotency for reliable distributed operations

In distributed systems, operations can be retried due to network failures, timeouts, or message duplication. Non-idempotent operations cause duplicate charges, double-sends, or data corruption.

Design operations so that executing them multiple times has the same effect as executing once:

1. Use idempotency keys for mutations:

POST /payments { idempotency_key: 'uuid-123', amount: 50 }
Server checks: already processed this key? Return cached result.

1. Make operations naturally idempotent:

Bad: UPDATE balance SET amount = amount + 50 (not idempotent)
Good: UPDATE balance SET amount = 150 WHERE version = 3 (idempotent)

1. Use unique constraints in the database:

INSERT INTO payments (idempotency_key, amount)
VALUES ('uuid-123', 50)
ON CONFLICT (idempotency_key) DO NOTHING;

1. PUT is idempotent, POST is not (by convention):

PUT /users/123 { name: 'Alice' } — safe to retry
POST /users { name: 'Alice' } — might create duplicates

1. Consumer-side deduplication for message queues:

Track processed message IDs, skip duplicates.

Networks are unreliable. Any operation that can be retried must produce the same result regardless of how many times it runs.