Idempotency - Useroutr

Networks fail. A request can succeed on Useroutr while your server never hears back. An idempotency key makes that safe: send the same request again with the same key and you get the original result, not a second funding intent.

const intent = await useroutr.fundingIntents.create(
  { amount: "25", asset: "asset_usdc_stellar", reference: order.id },
  { idempotencyKey: order.id },
);

Use a key that names the business action, like your order id, not a random value per attempt. Then a retry after a crash replays instead of duplicating.

How it works

The first request with a key runs, and its response is kept for 24 hours.
A repeat with the same key and the same body returns that response, with the header Idempotency-Replayed: true.
The same key with a different body is refused with 409 IDEMPOTENCY_KEY_REUSED.
A repeat that arrives while the first is still running gets 409 IDEMPOTENCY_REQUEST_IN_PROGRESS, which is retryable.
If the first request fails, the key is released so you can retry with it.

Keys are up to 255 characters and scoped to your application.

Where it applies

Request	Key
Create a funding intent	Required
Create a refund	Optional
Create a webhook endpoint, rotate its secret	Optional
Create an API key	Optional
Update requests (`PATCH`)	Not needed: they set absolute values
Revoke a key, retry a delivery	Not needed: repeating changes nothing

In the SDK

The SDK retries reads, and writes that carry an idempotency key, on timeouts, connection errors, 429 and server errors. A write without a key is never retried, so it can never be applied twice.

const { data, idempotencyReplayed } = await useroutr.request({
  method: "POST",
  path: "/v1/funding-intents",
  body: { amount: "25", asset: "asset_usdc_stellar" },
  idempotencyKey: "ORDER-1042",
});