> ## Documentation Index
> Fetch the complete documentation index at: https://docs.liquidramp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Retries

> When to retry API calls and how webhook delivery retries work.

Blind retries can create duplicate orders. Use [idempotency](/concepts/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](/concepts/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.

```javascript theme={null}
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:

1. Return `2xx` quickly
2. Be idempotent — the same `event` + `data.reference` may arrive more than once
3. 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.

## Related

* [Error handling](/guides/error-handling)
* [Callbacks](/concepts/callbacks)