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:
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.
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,useEnginexMutationstores the attempt per hook instance, and it survives options recreated on every render (React). orders.placeBatch(Predictions): the attempt lives in each result ofcreatePredictionsMutationsand stores the orders' keys even on a partial success; see Orders.withdrawals.confirmOtp: pass therequestIdreturned bywithdrawals.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.
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:
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.
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.