Idempotencia
Las operaciones que mueven dinero (depósito, retiro, apuesta, orden, opt-in y claim de bono) envían el header Idempotency-Key. El gateway guarda la respuesta por 72 horas: repetir el request con la misma clave no duplica la operación.
El SDK genera la clave automáticamente (una por llamada) y la mantiene en el retry interno tras renovar la sesión. Si llamas al módulo directamente (enginex.deposits.createPix), para repetir con seguridad después de un error de red genera la clave antes del primer intento y pasa la misma en idempotencyKey, en las opciones de la llamada. En las mutations (abajo) el SDK se encarga de esto:
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 forma parte de CallOptions y solo aplica a métodos idempotentes (los que mueven dinero); en los demás se ignora. Una cadena vacía se trata como ausente y el SDK genera la clave. Los paquetes de producto (@getenginex/sdk-igaming) siguen la misma regla: consulta Extensibilidad.
Cuándo el SDK reutiliza la clave
El gateway guarda la primera respuesta definitiva de cada clave por 72 horas y la repite para cualquier request con la misma clave. Por eso la clave solo debe reutilizarse cuando no sabes si el primer intento llegó. Las mutations del SDK (@getenginex/sdk/query, useEnginexMutation y los paquetes de producto) aplican esta regla por sí solas:
| Resultado del intento | ¿Ambiguo? | La clave... |
|---|---|---|
NETWORK_ERROR, TIMEOUT (la respuesta no llegó) | sí | se conserva para el próximo intento |
Error con status >= 500 | sí | se conserva para el próximo intento |
KEY_IN_USE (409: el intento anterior con la misma clave todavía se está procesando) | sí | se conserva para el próximo intento (una clave nueva duplicaría la operación) |
VALIDATION_ERROR después de un 2xx (la operación ocurrió, pero la respuesta llegó fuera de formato) | sí | se conserva para el próximo intento (el gateway devuelve la misma respuesta) |
| Éxito | no | se descarta (el mismo valor de nuevo es una operación nueva) |
Los demás 4xx (INSUFFICIENT_BALANCE, DEPOSIT_LIMIT_EXCEEDED, PAYMENT_FAILED, PAYLOAD_MISMATCH...) | no | se descarta |
CONFIGURATION_ERROR | no | se descarta |
ABORTED (cancelaste) | no | se descarta |
El intento abierto guarda la entrada y la clave, y la comparación es por el contenido de la entrada (claves de objeto en cualquier orden, undefined omitido), no por el objeto. Así que un "reintentar" con mutate({ amount: 5000 }) literal, después de un 503, reutiliza la clave; una entrada distinta empieza un intento nuevo y descarta el anterior. Dos llamadas simultáneas con la misma entrada, en el mismo objeto de opciones, usan la misma clave.
Dónde vive el intento:
- Core y TanStack: en cada objeto de opciones (
m.deposits.createPix()); cada llamada a la fábrica tiene el suyo. En React,useEnginexMutationguarda el intento por instancia del hook, y sobrevive a las opciones recreadas en cada render (React). orders.placeBatch(Predictions): el intento queda en cada resultado decreatePredictionsMutationsy guarda las claves de las órdenes incluso en un éxito parcial; consulta Órdenes.withdrawals.confirmOtp: pasa elrequestIddevuelto porwithdrawals.request(confirmOtp({ otp, requestId })). No va al gateway: solo separa los desafíos, y un desafío nuevo nunca reutiliza la clave del anterior.
ABORTED libera la clave
Un request cancelado puede haber llegado al gateway. Quien cancela y quiere repetir la misma operación pasa idempotencyKey (abajo); sin ella, la llamada siguiente es una operación nueva.
Otros códigos que puedes ver del gateway:
KEY_IN_USE(409): el primer intento todavía se está procesando (doble clic, otra pestaña). Espera y repite con la misma entrada: las mutations mantienen la clave (tabla de arriba) y el gateway devuelve la respuesta de la primera, si se procesó.PAYLOAD_MISMATCH(422): la clave ya se usó con otro cuerpo (otro monto, otra clave PIX). Como el SDK renueva la clave cuando cambia la entrada, esto solo ocurre con una clave explícita reutilizada en otra operación: genera una por operación, nunca por pantalla.
Después de expirar
Después del expiresAt de un cobro PIX o de un código OTP de retiro, un nuevo pedido con la clave antigua devolvería el mismo cobro (o el mismo pedido) ya vencido. Como esas respuestas son éxitos, la clave ya se descartó: el próximo pedido es nuevo.
Clave explícita
Para repetir después de recargar la página, o después de un ABORTED, guarda la clave tú mismo y pasa idempotencyKey: gana sobre el intento del SDK y aplica a toda llamada de esas opciones. Genera una por operación, cuando el jugador confirma, no una por pantalla:
const key = crypto.randomUUID() // one per operation, not per attempt
sessionStorage.setItem('pix-key', key)
await enginex.deposits.createPix({ amount: 5000 }, { idempotencyKey: key })En mutations (m.deposits.createPix({ idempotencyKey })), la clave se lee cuando se llama a la fábrica y entra en las opciones del render, así que mutate debe ejecutarse después del render que la recibió; el ejemplo está en React.
La clave se aplica por usuario y por ruta: la misma cadena en deposits.createPix y en withdrawals.request son operaciones independientes, pero no es buena práctica reutilizarla.
Sin Web Crypto (crypto.randomUUID y crypto.getRandomValues ausentes), generar la clave rechaza con CONFIGURATION_ERROR. En HTTP en la LAN (origen inseguro, sin randomUUID), el SDK usa getRandomValues y sigue funcionando.
Métodos idempotentes
| Método | Ruta |
|---|---|
deposits.createPix | POST /deposits/pix |
withdrawals.request | POST /withdrawals |
withdrawals.confirmOtp | POST /withdrawals/confirm-otp |
En los demás métodos (incluidos withdrawals.cancel y pixKeys.*), idempotencyKey se ignora: el gateway no aplica idempotencia a esas rutas.