Idempotência
Operações que movimentam dinheiro (depósito, saque, aposta, ordem, opt-in e claim de bônus) enviam o header Idempotency-Key. O gateway guarda a resposta por 72 horas: repetir o request com a mesma chave não duplica a operação.
O SDK gera a chave automaticamente (uma por chamada) e a mantém no retry interno após renovar a sessão. Chamando o módulo direto (enginex.deposits.createPix), para repetir com segurança depois de um erro de rede gere a chave antes da primeira tentativa e passe a mesma em idempotencyKey, nas opções da chamada. Nas mutations (abaixo) o SDK cuida disso:
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 faz parte de CallOptions e só vale para métodos idempotentes (os que movimentam dinheiro); nos demais é ignorada. Texto vazio é tratado como ausente e o SDK gera a chave. Pacotes de produto (@getenginex/sdk-igaming) seguem a mesma regra: veja Extensibilidade.
Quando o SDK reaproveita a chave
O gateway guarda a primeira resposta definitiva de cada chave por 72 horas e a repete para qualquer request com a mesma chave. Por isso a chave só deve ser reaproveitada quando você não sabe se a primeira tentativa chegou. As mutations do SDK (@getenginex/sdk/query, useEnginexMutation e os pacotes de produto) aplicam essa regra sozinhas:
| Resultado da tentativa | Ambíguo? | A chave... |
|---|---|---|
NETWORK_ERROR, TIMEOUT (a resposta não chegou) | sim | fica para a próxima tentativa |
Erro com status >= 500 | sim | fica para a próxima tentativa |
KEY_IN_USE (409: a tentativa anterior com a mesma chave ainda está em processamento) | sim | fica para a próxima tentativa (uma chave nova duplicaria a operação) |
VALIDATION_ERROR depois de 2xx (a operação aconteceu, mas a resposta veio fora do formato) | sim | fica para a próxima tentativa (o gateway devolve a mesma resposta) |
| Sucesso | não | é descartada (o mesmo valor de novo é uma operação nova) |
Os demais 4xx (INSUFFICIENT_BALANCE, DEPOSIT_LIMIT_EXCEEDED, PAYMENT_FAILED, PAYLOAD_MISMATCH...) | não | é descartada |
CONFIGURATION_ERROR | não | é descartada |
ABORTED (você cancelou) | não | é descartada |
A tentativa em aberto guarda a entrada e a chave, e a comparação é pelo conteúdo da entrada (chaves de objeto em qualquer ordem, undefined omitido), não pelo objeto. Então um "tentar de novo" com mutate({ amount: 5000 }) literal, depois de um 503, reaproveita a chave; uma entrada diferente começa uma tentativa nova e descarta a anterior. Duas chamadas simultâneas com a mesma entrada, no mesmo objeto de opções, usam a mesma chave.
Onde a tentativa mora:
- Core e TanStack: em cada objeto de opções (
m.deposits.createPix()); cada chamada da fábrica tem a sua. No React, ouseEnginexMutationguarda a tentativa por instância do hook, e ela sobrevive às opções recriadas a cada render (React). orders.placeBatch(Predictions): a tentativa fica em cada resultado decreatePredictionsMutationse guarda as chaves das ordens mesmo num sucesso parcial; veja Ordens.withdrawals.confirmOtp: passe orequestIddevolvido porwithdrawals.request(confirmOtp({ otp, requestId })). Ele não vai ao gateway: só separa os desafios, e um desafio novo nunca reaproveita a chave do anterior.
ABORTED libera a chave
Um request cancelado pode ter chegado ao gateway. Quem cancela e quer repetir a mesma operação passa idempotencyKey (abaixo); sem ela, a chamada seguinte é uma operação nova.
Outros códigos que você pode ver do gateway:
KEY_IN_USE(409): a primeira tentativa ainda está em processamento (clique duplo, outra aba). Espere e repita com a mesma entrada: as mutations mantêm a chave (tabela acima) e o gateway devolve a resposta da primeira, se ela foi processada.PAYLOAD_MISMATCH(422): a chave já foi usada com outro corpo (outro valor, outra chave PIX). Como o SDK renova a chave quando a entrada muda, isso só acontece com chave explícita reusada em outra operação: gere uma por operação, nunca por tela.
Depois de expirar
Depois do expiresAt de uma cobrança PIX ou de um código OTP de saque, um novo pedido com a chave antiga devolveria a mesma cobrança (ou o mesmo pedido) já vencida. Como essas respostas são sucessos, a chave já foi descartada: o próximo pedido é novo.
Chave explícita
Para repetir depois de recarregar a página, ou depois de um ABORTED, guarde a chave você mesmo e passe idempotencyKey: ela vence a tentativa do SDK e vale para toda chamada daquelas opções. Gere uma por operação, quando o jogador confirma, não uma por tela:
const key = crypto.randomUUID() // one per operation, not per attempt
sessionStorage.setItem('pix-key', key)
await enginex.deposits.createPix({ amount: 5000 }, { idempotencyKey: key })Em mutations (m.deposits.createPix({ idempotencyKey })), a chave é lida quando a fábrica é chamada e entra nas opções do render, então o mutate precisa rodar depois do render que a recebeu; o exemplo está em React.
A chave vale por usuário e por rota: a mesma string em deposits.createPix e em withdrawals.request são operações independentes, mas não é boa prática reaproveitá-la.
Sem Web Crypto (crypto.randomUUID e crypto.getRandomValues ausentes), gerar a chave rejeita com CONFIGURATION_ERROR. Em HTTP na LAN (origem insegura, sem randomUUID), o SDK usa getRandomValues e segue funcionando.
Métodos idempotentes
| Método | Rota |
|---|---|
deposits.createPix | POST /deposits/pix |
withdrawals.request | POST /withdrawals |
withdrawals.confirmOtp | POST /withdrawals/confirm-otp |
Nos demais métodos (inclusive withdrawals.cancel e pixKeys.*), idempotencyKey é ignorada: o gateway não aplica idempotência a essas rotas.