Idempotency & Safety

Two properties decide whether a request can be safely repeated. They are easy to mix up, so let’s pin them down precisely.

Safe vs idempotent

• Safe — the request has no observable effect on server state; it only reads. GET, HEAD, and OPTIONS are safe.
• Idempotent — making the request N times leaves the server in the same state as making it once. GET, HEAD, OPTIONS, PUT, and DELETE are idempotent. POST and (in general) PATCH are not.

Every safe method is idempotent, but not every idempotent method is safe — DELETE changes state yet is idempotent.

flowchart TD
  M{Method} --> GET[GET / HEAD: safe + idempotent]
  M --> PUTDEL[PUT / DELETE: idempotent, not safe]
  M --> POST[POST: neither]
  M --> PATCH[PATCH: usually neither]

Where each method sits on the safe/idempotent grid

Why it matters: retries

Networks drop responses. When a client (or proxy, or load balancer) does not hear back, it may retry. If the method is idempotent, retrying is harmless. If it is not — like a POST that charges a card — a blind retry could charge twice.

JavaScriptRun ▸Open in StackBlitz ▸

// A PUT is idempotent: applying it twice == applying it once. const store = { 42: { id: 42, status: 'draft' } }; function putStatus(id, status) { store[id] = { ...store[id], status }; return store[id]; } console.log(putStatus(42, 'published')); // first attempt console.log(putStatus(42, 'published')); // retry after a dropped response console.log('final state:', store[42]); // same as one call

Making POST safe to retry

When you genuinely need a non-idempotent create to tolerate retries, use an idempotency key: the client sends a unique Idempotency-Key header, and the server remembers the result for that key so a repeat returns the original outcome instead of acting twice. We cover the mechanics in Versioning & Caching.

Common mistakes

A non-idempotent POST with no guard Symptom:

• A user double-clicks submit — two orders get created
• A network retry charges a card twice
• Require an idempotency key for sensitive POSTs like payments

A PATCH that’s deliberately not idempotent Symptom:

• PATCH /accounts/\{id\}/balance with { "increment": 100 } — repeating it adds again
• A client retry silently inflates the balance
• Use an absolute value instead: { "balance": 1100 }

💡 Real-world examples

Stripe API:

• An Idempotency-Key header on POST /charges
• Send the same key again and Stripe returns the original response instead of charging again
• The client can store the key and retry safely

AWS S3:

• PUT object is idempotent — uploading the same file again overwrites it instead of duplicating it
• Makes retries safe for large file uploads

Sources: Stripe idempotent requests, AWS S3 PutObject

🌐 Design for the retry you cannot see

Assume every non-safe request might arrive more than once. Make writes idempotent where you can (prefer PUT with a client-chosen ID), and protect the ones you cannot with an idempotency key. Correctness under retries is a design choice, not luck.

Which statement is true?

Every idempotent method is also safe Every safe method is also idempotent POST is idempotent DELETE is safe

Why is retrying a non-idempotent POST risky?

It is slower It may perform the action twice (e.g. charge twice) It cannot be cached It returns the wrong status code

What lets a non-idempotent create tolerate retries safely?

A larger timeout An Idempotency-Key the server remembers Using GET instead A 500 response

Submit

Mark as complete