Idempotency - Suby.fi

A request can time out after the server created a payment. Retrying blindly would charge twice. Send an Idempotency-Key header and the retry replays the original response instead of running again.

curl https://api.suby.fi/v3/payments/off-session \
  -H "X-Suby-Api-Key: sk_live_…" \
  -H "Idempotency-Key: 5f3b9c2e-1a4d-4f2b-9c31-7e2a1b6d8c04" \
  -H "Content-Type: application/json" \
  -d '{ "offSession": true,
        "customer": { "id": "cus_…" }, "customerPaymentMethodId": "pi_…",
        "productId": "pro_…", "priceCents": "999" }'

Optional, but recommended on every state-changing POST · a duplicated debit is the one mistake a retry can make that the buyer notices. Use a UUID v4: one per logical operation, reused on retry.

Behaviour

Situation	Result
Same key, same request	Original response replayed · same status, same body.
Same key, different body or path	`422 IDEMPOTENCY_KEY_CONFLICT`
Same key, first request still running	`409 IDEMPOTENCY_KEY_CONFLICT` · wait and retry.
Same key, older than 24 h	Treated as new · the operation runs again.

5xx responses are not cached: the key is released so you can retry. 2xx and 4xx are cached.

Scope


Scope	Per account and environment · a sandbox and a live key never collide.
Binding	Method + path + body.
Retention	24 hours.
Methods	`POST` only. `PATCH` is not deduplicated.
Max length	255 characters.

Not the same as `externalRef`

Idempotency-Key is a per-request token that deduplicates a retried HTTP call, and expires in 24 h. externalRef is your business reference (an order id) · it can appear on several payments and never deduplicates anything.