← Integration Engineering
Integration Engineering

Idempotency: Sending the Same Request Twice Must Not Do It Twice

6 Oct 2026·3 min read

You send a request to create a payment. Nothing comes back, and your code times out. Maybe the payment never happened. Maybe it did, and only the reply got lost. From your side, both look the same.

What the word means

Idempotent means doing it again gives the same result as doing it once. Pressing a lift button five times still calls one lift. Adding an item to a cart five times gives five items. Retries are only safe for idempotent actions.

  • GET, PUT and DELETE are idempotent. Sending them twice has the same effect as once.
  • POST usually creates a new thing each time. Not idempotent.

Making POST safe

Many payment APIs, like Stripe, accept an Idempotency-Key header. You make up a unique value once per action. Send the same key on a retry, and the API returns the first result instead of creating it again.

POST /v1/payments HTTP/1.1
Host: api.example.com
Content-Type: application/json
Idempotency-Key: 3f9c1a52-8d4e-4b7a-9f21-6c0e5d8b2a17

{ "amount": 5000, "currency": "pkr", "order_id": "ORD-1042" }
Example request: the shape, not a real endpoint. The header name is real (Stripe uses it); the host and body are made up.

Do not make a new key inside the retry loop, or every retry looks new. No key support? Look it up first and create only if it is missing. If you truly cannot know, do not retry. Alert a human.

Do this in 60 secondsFind a POST in your code with a retry around it. If the first attempt worked but the reply was lost, what does the retry do? If it creates it again, that is your next fix.
Today’s AI angleWhen a tool call times out, an AI agent tends to call it again. For "create invoice", that is a problem. Make create tools idempotent on your side, so the agent’s retry cannot do the work twice.
Idempotency: Sending the Same Request Twice Must Not Do It Twice · Ali Huzaifa