Saltar al contenido principal

Idempotency

Toda operación con relevancia financiera que muta estado acepta una idempotency key. Enviar la misma key con el mismo payload siempre es seguro — devuelve el resultado original en vez de ejecutar de nuevo. Enviar la misma key con un payload distinto se rechaza con IDEMPOTENCY_KEY_CONFLICT (409, ver Errors § Conflictos de idempotencia) — nunca sobrescribe ni ejecuta por duplicado en silencio.

Dónde va la key​

Existen dos mecanismos reales, y cuál aplica depende de la ruta específica:

  • Campo del cuerpo (el caso común) — un parámetro opcional idempotencyKey en operaciones como crear una Transaction, un PaymentIntent, ejecutar un Settlement o un Refund, solicitar un Withdrawal, o ingerir un Event.
  • Header Idempotency-Key — usado solo por dos rutas: crear una Organization y crear una Application. Si estás llamando directamente por HTTP en vez de a través de un SDK, revisa qué mecanismo documenta la página de API Reference de la operación específica.

Si omites la key por completo, cada SDK oficial genera un UUID v4 aleatorio automáticamente — lo que significa que una llamada de SDK sin key explícita no es idempotente entre llamadas separadas (cada una genera su propia key). Pasa siempre una key explícita y determinística cuando realmente necesites seguridad ante replay (ej.: derivada de tu propio ID de pedido o de un request ID que controles) — el valor autogenerado por defecto solo protege los reintentos internos de una sola llamada, nunca dos llamadas independientes que debían haber sido "la misma" operación.

Comportamiento de reintento​

La propia lógica de reintento automático de un SDK (fallos de red, 5xx, rate limiting) siempre reutiliza la misma key del primer intento — nunca genera una key nueva por intento. Esto es lo que hace seguros los reintentos automáticos por defecto: una llamada reintentada que en realidad ya tuvo éxito del lado del servidor en un intento anterior repite ese mismo resultado en vez de ejecutarse una segunda vez.

Qué significa "mismo payload"​

La plataforma compara el payload asociado a una key ya usada con el payload de la nueva solicitud. Si coinciden, recibes de vuelta el resultado original (replay, no una ejecución nueva — sin efecto financiero duplicado). Si difieren en algún campo que la plataforma considere significativo, recibes IDEMPOTENCY_KEY_CONFLICT. Nunca reutilices una key entre dos operaciones conceptualmente distintas, aunque esperes que el conflicto sea inofensivo — trata una key como una identidad única para una operación específica pretendida.

Ejemplo​

// Key determinística derivada de tu propio ID de pedido -- seguro para reintentar esta llamada
// exacta cuantas veces haga falta; nunca derivada de Date.now()/Math.random(), lo que anularía
// todo el mecanismo.
const idempotencyKey = `settle-order-${orderId}`;

const settlement = await client.settlements.executeSettlement(transactionId, undefined, idempotencyKey);