Skip to content

Idempotency

Repeat a write safely with an Idempotency-Key, and what a repeat answers.

Updated

A network can lose an answer after a write landed. Send an Idempotency-Key header with the write, and repeating it with the same key answers what the first call did instead of writing again.

Keys

  • A key is 1 to 255 visible ASCII characters, no spaces. Make it unique per change you mean (a UUID, or a name tied to it like publish-watercolor-basics), and reuse it only to repeat that same change.
  • A key is kept for 24 hours, and belongs to the token and the store: another token, or another store, starts afresh.
  • The first call answers Idempotent-Replayed: false. A repeat within 24 hours answers what the first call answered, with its status, and Idempotent-Replayed: true. A repeat that comes while the first is still running waits for it, then answers the same.
  • The same key with other arguments, or on another operation, answers 409 conflict on the field idempotency_key, and changes nothing.
  • A write that fails records nothing, so a repeat after a refusal runs again. A bulk call is the exception: it lands with its refused items, so a repeat answers the same refusals.

When the first answer couldn’t be kept (it was over 512 KiB, a customer of the store was erased since, or the token lost a scope the answer was read under), a repeat answers 409 with context.current: "applied": the write landed once, so read the state back.

curl -X POST 'https://api.sherpo.io/merchant/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/publish' \
  -H "Authorization: Bearer $SHERPO_TOKEN" \
  -H 'Idempotency-Key: publish-watercolor-basics'
const answer = await sherpo('POST', '/v1/stores/STORE_ID/products/6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42/publish', {
  key: 'publish-watercolor-basics',
});

Answers 200, abridged:

{
  "id": "6f1c2a9e-4b7d-4e2a-9c51-0d3e8b7a1f42",
  "status": "published",
  "published_at": "2026-11-03T10:00:00.000Z"
}

Which writes take one

A write takes a key when its reference page lists the Idempotency-Key header. Most writes do. Those that don’t refuse the header as 422 invalid at the path ["headers", "idempotency-key"], as reads and the /v1/merchants operations do:

Retrying safely

Retry a write after a timeout, a lost connection, a 500 internal or a 503, with the same key and the same arguments. Without a key, read the state back first: the write may have landed.

Type to search…

↑↓ navigate↵ selectEsc close