Idempotency and retries

Networks fail: a request can time out after the API did its work. So every POST carries an Idempotency-Key header, 1 to 255 visible ASCII characters, such as a UUID or your order's ID, and the API remembers each key's answer:

• The same request with the same key returns the first answer again, with Idempotent-Replayed: true, instead of making a second payment or payout.
• The same key with a different request is refused with idempotency_key_reused, and isn't retried.
• While the first is still running, a repeat gets 409 idempotency_key_in_progress with a Retry-After.
• A request that failed isn't stored, so a retry with the same key runs it again. That is safe: the failed attempt changed nothing.

const again = await nowgate.payments
  .create(
    { network: "tron", asset: "USDT", amount: "25.00", order_id: "1042" },
    { idempotencyKey: orderKey },
  )
  .withResponse();

again = client.with_response.payments.create(
    network="tron",
    asset="USDT",
    amount="25.00",
    order_id="1042",
    idempotency_key=order_key,
)

$again = $nowgate->withResponse()->payments->create(
    ['network' => 'tron', 'asset' => 'USDT', 'amount' => '25.00', 'order_id' => '1042'],
    ['idempotency_key' => $orderKey],
);

What the SDKs retry#

The SDKs send a key with every POST, yours or a random UUID, and the same one on every attempt of a call. Pass your own (your order's ID, say) to make a retry safe across your own process's restarts too.

• Two retries by default, so at most three attempts: maxRetries / max_retries, per client or per call.
• The wait: Retry-After when the answer has one, up to 60 seconds; a longer one isn't waited for, and the error carries it as retry_after. Otherwise 0.5, 1, 2, 4 and at most 8 seconds, each a random fraction of that, so many clients don't retry in step.
• GET, PUT, PATCH and DELETE are retried by the same rules: repeating them changes nothing more.

Without an SDK, retry with the same key only after no answer, 409, 429 and 5xx, and honor Retry-After.