Idempotency — EPD Commerce

What this is and who needs it

Networks fail. Servers time out. Sometimes a request reaches EPD and succeeds, but the response never makes it back to your code — and your retry creates a second customer, a second charge, a second subscription.

Idempotency keys solve that. Send a unique key with every write, and EPD will guarantee that the same key produces the same response, even if you retry it ten times.

If you write any code that creates, updates, or deletes data through this API, you should use idempotency keys.

How it works

Generate one key per logical action

A “logical action” is one thing the user is trying to do — charge their card, sign up for a plan, refund an order. Use a UUID v4 (or any 16–64 character string of letters, digits, hyphens, or underscores).

Send it on every write request

Add the X-EPD-Idempotency-Key header to POST, PATCH, and DELETE calls. EPD stores the key and the full response for 24 hours.

Retry with the same key

A retry with the same key returns the original response — your code sees the action happen exactly once, no matter how many times you call it.

The header

X-EPD-Idempotency-Key: 8e2c1b9a-4f3d-4f9e-9b1a-1c7e2d3f4a5b

Property	Value
Header name	`X-EPD-Idempotency-Key`
Format	16–64 characters; letters, digits, hyphens, underscores
Recommended	UUID v4
Storage window	24 hours from first request
Applies to	`POST`, `PATCH`, `DELETE`

Example

curl https://api.epd.com/v1/orders \
  -H "Authorization: Bearer $EPD_KEY" \
  -H "epd-version: 2026-02-11" \
  -H "X-EPD-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "550e8400-e29b-41d4-a716-446655440000",
    "payment_method_id": "6ba7b815-9dad-11d1-80b4-00c04fd430c8",
    "items": [
      { "product_id": "6ba7b810-9dad-11d1-80b4-00c04fd430d1", "quantity": 1 }
    ]
  }'

import crypto from "node:crypto";

const idempotencyKey = crypto.randomUUID();

await fetch("https://api.epd.com/v1/orders", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.EPD_KEY}`,
    "epd-version": "2026-02-11",
    "X-EPD-Idempotency-Key": idempotencyKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    customer_id: "550e8400-e29b-41d4-a716-446655440000",
    payment_method_id: "6ba7b815-9dad-11d1-80b4-00c04fd430c8",
    items: [
      { product_id: "6ba7b810-9dad-11d1-80b4-00c04fd430d1", quantity: 1 },
    ],
  }),
});

Errors you may see

Error code	Status	What it means
`idempotency_key_in_use`	409	A request with this key is already in flight. Retry after a short delay.
`idempotency_key_conflict`	409	You reused a key that was previously paired with a different payload. Use a fresh key for new actions.
`missing_idempotency_key`	400	A required idempotency header was not sent (some endpoints make it mandatory).
`invalid_idempotency_key`	400	The key is empty, too long, or contains invalid characters.

Best practices

Generate the key before you make the request, store it, and reuse it on every retry of that same logical action. If you generate a fresh UUID on each retry, you defeat the whole mechanism.

Never reuse a key for different intents. The replayed response will not match your new payload, and EPD will reject the call with idempotency_key_conflict.