Skip to main content

Idempotency

A network failure on a write leaves you unable to tell whether it succeeded. Retrying blind risks a duplicate; not retrying risks a lost record.

Send an Idempotency-Key and the ambiguity disappears:

Idempotency-Key: 9f8b7a6c-5d4e-3f2a-1b0c-9d8e7f6a5b4c

MineTech stores the response against that key for 24 hours. Replaying the same key returns the original response — status, body and all — without performing the operation again. The replay is marked:

x-idempotent-replay: true

A request sent with a key that is still in flight gets 409 rather than executing twice.

The SDK does this for you​

Every POST, PUT, PATCH and DELETE gets a generated key automatically, and the same key is reused across the SDK's internal retries. That pairing is what makes retrying a POST safe at all — a fresh key per attempt would let a retried create produce duplicates, which is worse than not retrying.

Supply your own to dedupe across processes or runs:

// Two workers picking up the same job produce one invoice, not two.
await client.finance.invoices.create(payload, {
  idempotencyKey: `invoice-${jobId}`,
});

Choosing a key​

Derive it from the thing you are creating, not from the attempt:

  • Good — invoice-2026-03-site-7, payroll-batch-${batchId}
  • Bad — Date.now(), a fresh UUID per attempt (defeats the purpose)

Scope and lifetime​

Keys are scoped to your tenant, so they cannot collide with another customer's. They expire after 24 hours — comfortably longer than any retry sequence, and short enough that reusing a key for genuinely new work months later behaves as expected.

Changing the body reuses the stored response

The key identifies the operation. Sending a different body under a key that has already completed returns the original response; it does not apply the new body. Use a new key for new work.