Idempotency

The Idempotency-Key header

Send an Idempotency-Key header on write operations. The value must be a lowercase UUID v4, generated fresh for each logical attempt and reused for every retry of that attempt.

curl -X POST "https://www.membber.com/api/v1/orders" \
  -H "Authorization: Bearer $MEMBBER_TOKEN" \
  -H "Idempotency-Key: 1f0e2d3c-4b5a-4678-9abc-def012345678" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

import { createMembberClient } from "@membber/sdk-ts";

const membber = createMembberClient({
  getAccessToken: () => process.env.MEMBBER_TOKEN,
});

// One key per logical attempt: generate it when the user taps Pay,
// reuse it for every retry of that same attempt.
const idempotencyKey = crypto.randomUUID();

const { data, error } = await membber.createOrder({
  headers: { "Idempotency-Key": idempotencyKey },
  body: { /* ... */ },
});

Which operations require it

Operations that move money or create customer records, such as creating orders and memberships, require the header outright: calling them without one returns 400 IDEMPOTENCY_KEY_REQUIRED, so the API tells you rather than leaving it to memory. All other writes are idempotent at the data layer, which means retrying them cannot double-apply; the header is accepted and ignored there, so the simplest correct client sends it on every write.

Replay behaviour

• Same key, same body, within the replay window (10 minutes): you get the original response back, byte for byte. The write happens once.
• Same key, different body: rejected with 422 IDEMPOTENCY_KEY_REUSED. A key identifies one attempt; changing the payload means a new attempt and a new key.
• Invalid key format (not a lowercase UUID v4): rejected with 400 VALIDATION_ERROR.

The pattern that always works

1. Generate a UUID when the user commits the action.
2. Attach it to the write and to every retry of that write.
3. On network failure or a 5xx, retry with backoff, same key, same body.
4. On a 4xx other than 429, stop: the request itself needs fixing. See Errors.