---
url: https://game-engine-io.github.io/enginex-frontend-sdk/concepts/idempotency.md
---
# Idempotency

Operations that move money (deposit, withdrawal, bet, order, bonus opt-in and claim) send the
`Idempotency-Key` header. The gateway stores the response for 72 hours: repeating the request with the same
key does not duplicate the operation.

The SDK generates the key automatically (one per call) and keeps it on the internal retry after renewing the
session. When calling the module directly (`enginex.deposits.createPix`), to safely repeat after
a network error, generate the key **before** the first attempt and pass the same one in `idempotencyKey`, in the
call options. In mutations (below) the SDK takes care of this:

```ts
import { isEnginexError } from '@getenginex/sdk'

const key = crypto.randomUUID() // one per operation, not per attempt
try {
  await enginex.deposits.createPix({ amount: 5000 }, { idempotencyKey: key })
} catch (e) {
  if (isEnginexError(e, 'NETWORK_ERROR')) {
    await enginex.deposits.createPix({ amount: 5000 }, { idempotencyKey: key }) // does not duplicate
  }
}
```

`idempotencyKey` is part of `CallOptions` and only applies to idempotent methods (those that move
money); on the others it is ignored. An empty string is treated as absent and the SDK generates the key. Product
packages (`@getenginex/sdk-igaming`) follow the same rule: see
[Extensibility](/concepts/extensibility).

## When the SDK reuses the key

The gateway stores the **first definitive response** of each key for 72 hours and repeats it for
any request with the same key. That is why the key should only be reused when you do not know whether
the first attempt arrived. The SDK's mutations (`@getenginex/sdk/query`, `useEnginexMutation` and the
product packages) apply this rule on their own:

| Attempt result | Ambiguous? | The key... |
|---|---|---|
| `NETWORK_ERROR`, `TIMEOUT` (the response did not arrive) | yes | is kept for the next attempt |
| Error with `status >= 500` | yes | is kept for the next attempt |
| `KEY_IN_USE` (409: the previous attempt with the same key is still being processed) | yes | is kept for the next attempt (a new key would duplicate the operation) |
| `VALIDATION_ERROR` after a 2xx (the operation happened, but the response came back out of format) | yes | is kept for the next attempt (the gateway returns the same response) |
| Success | no | is discarded (the same value again is a new operation) |
| The other 4xx (`INSUFFICIENT_BALANCE`, `DEPOSIT_LIMIT_EXCEEDED`, `PAYMENT_FAILED`, `PAYLOAD_MISMATCH`...) | no | is discarded |
| `CONFIGURATION_ERROR` | no | is discarded |
| `ABORTED` (you canceled) | no | is discarded |

The open attempt stores the input and the key, and the comparison is by the **content** of the input
(object keys in any order, `undefined` omitted), not by the object. So a "try again"
with a literal `mutate({ amount: 5000 })`, after a 503, reuses the key; a different input
starts a new attempt and discards the previous one. Two simultaneous calls with the same input, on the same
options object, use the same key.

Where the attempt lives:

* **Core and TanStack:** in each options object (`m.deposits.createPix()`); each call to the factory
  has its own. In React, `useEnginexMutation` stores the attempt per **hook instance**, and it
  survives options recreated on every render ([React](/frameworks/react#idempotency-in-mutations)).
* **`orders.placeBatch` (Predictions):** the attempt lives in each result of
  `createPredictionsMutations` and stores the orders' keys even on a partial success; see
  [Orders](/predictions/orders).
* **`withdrawals.confirmOtp`:** pass the `requestId` returned by `withdrawals.request`
  (`confirmOtp({ otp, requestId })`). It does not go to the gateway: it only separates the challenges, and a new
  challenge never reuses the previous one's key.

::: warning ABORTED releases the key
A canceled request may have reached the gateway. Whoever cancels and wants to repeat **the same** operation
passes `idempotencyKey` (below); without it, the next call is a new operation.
:::

Other codes you may see from the gateway:

* `KEY_IN_USE` (409): the first attempt is still being processed (double click, another tab). Wait
  and repeat with the same input: the mutations keep the key (table above) and the gateway returns the first
  one's response, if it was processed.
* `PAYLOAD_MISMATCH` (422): the key was already used with another body (another amount, another PIX key). Since the
  SDK renews the key when the input changes, this only happens with an explicit key reused on another
  operation: generate one per operation, never per screen.

### After expiry

After the `expiresAt` of a PIX charge or a withdrawal OTP code, a new request with the old key
would return the same already-expired charge (or request). Since those responses are successes, the key was already
discarded: the next request is new.

## Explicit key

To repeat after reloading the page, or after an `ABORTED`, store the key yourself and pass
`idempotencyKey`: it **wins** over the SDK's attempt and applies to every call of those options. Generate one per
operation, when the player confirms, not one per screen:

```ts
const key = crypto.randomUUID() // one per operation, not per attempt
sessionStorage.setItem('pix-key', key)
await enginex.deposits.createPix({ amount: 5000 }, { idempotencyKey: key })
```

In mutations (`m.deposits.createPix({ idempotencyKey })`), the key is read when the factory is called and
goes into the render's options, so `mutate` must run **after** the render that received it; the
example is in [React](/frameworks/react#idempotency-in-mutations).

The key applies per user and per route: the same string on `deposits.createPix` and on
`withdrawals.request` are independent operations, but reusing it is not good practice.

Without Web Crypto (`crypto.randomUUID` and `crypto.getRandomValues` absent), generating the key rejects with
`CONFIGURATION_ERROR`. On HTTP over the LAN (insecure origin, no `randomUUID`), the SDK uses `getRandomValues`
and keeps working.

## Idempotent methods

| Method | Route |
|---|---|
| `deposits.createPix` | `POST /deposits/pix` |
| `withdrawals.request` | `POST /withdrawals` |
| `withdrawals.confirmOtp` | `POST /withdrawals/confirm-otp` |

On the other methods (including `withdrawals.cancel` and `pixKeys.*`), `idempotencyKey` is ignored: the
gateway does not apply idempotency to those routes.
