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

# Idempotency

> How to safely retry requests without creating duplicate orders or payments.

Network failures can leave you unsure whether a request succeeded. ProxyJam supports idempotency on create operations so you can retry safely.

## How it works

Include a unique `idempotency_key` (UUID) in your request body. If you send the same key again, the API returns the original response instead of creating a new resource.

```json theme={null}
{
  "offer_id": 42,
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  ...
}
```

## Endpoints that support idempotency keys

| Endpoint                         | Field                                                                                |
| -------------------------------- | ------------------------------------------------------------------------------------ |
| `POST /orders`                   | `idempotency_key` in request body                                                    |
| `POST /orders/guest`             | `idempotency_key` in request body                                                    |
| `POST /orders/{order_id}/extend` | `Idempotency-Key` header (required for mobile rotating; optional for static proxies) |
| `POST /payments/payment-intents` | `Idempotency-Key` header (required)                                                  |

## Header-based idempotency

Some endpoints take the idempotency key as the HTTP `Idempotency-Key` header rather than a body field:

```
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
```

<Warning>
  The `Idempotency-Key` header is **required** for `POST /payments/payment-intents` and for mobile-rotating calls to `POST /orders/{order_id}/extend`. Requests will be rejected without it.
</Warning>

A replay with the same key returns the cached response. A different request body sent with the same key returns `409 ConflictError`.

## Best practices

* Generate a new UUID for each unique operation. Never reuse a key for a different operation.
* Store the key before making the request so you can resend it on retry.
* Keys are scoped per user — the same key used by two different users creates two separate resources.