Retries - Liquidramp

Blind retries can create duplicate orders. Use idempotency patterns on writes.

API call retries

HTTP status	Retry?	Notes
`2xx`	No	Success
`400`, `401`, `403`, `404`, `422`	No	Fix the request
`429`	Yes	Back off; see Rate limits
`5xx`	Yes	Use the same `merchant_reference`
Timeout / connection reset	Yes	Treat as ambiguous; deduplicate with `merchant_reference`

Use exponential backoff with jitter.

async function withRetry(fn, { maxAttempts = 3, baseMs = 1000, capMs = 30000 } = {}) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      const retryable = err.status === 429 || err.status >= 500 || err.code === "ETIMEDOUT";
      if (!retryable || attempt === maxAttempts - 1) throw err;
      const delay = Math.min(capMs, baseMs * 2 ** attempt) + Math.random() * 1000;
      await sleep(err.retryAfter ? err.retryAfter * 1000 : delay);
    }
  }
}

Never retry a POST /v1/orders that may have succeeded without using the same merchant_reference.

Webhook delivery retries

Failed outbound deliveries are retried with backoff. Inspect attempts in the partner portal. Your handler must:

Return 2xx quickly
Be idempotent — the same event + data.reference may arrive more than once
Verify HMAC before processing

You can optionally call POST /v1/orders/:reference/fulfill while the order is still awaiting payment if auto-detection is delayed.