Idempotencia y reintentos

¿Qué es la idempotencia?

La idempotencia garantiza que ejecutar el mismo request múltiples veces produce el mismo resultado que ejecutarlo una sola vez.

En Rivopay, puedes usar el header x-idempotency-key para evitar crear QRs o pay-outs duplicados cuando retries un request.

Cómo usarlo

Agrega el header en tu request:

POST /v1/br/payin/pix/instant
x-idempotency-key: 550e8400-e29b-41d4-a716-446655440000

• El valor debe ser un UUID v4 generado por ti
• Mismo key → misma transacción (no se crea una nueva)
• El key es válido durante la ventana de la transacción

Cuándo usar idempotencia

• En todos los reintentos después de errores de red o timeouts
• Cuando el status del request original es incierto (no sabes si llegó al server)
• No en requests completamente nuevos

Ejemplo con reintentos

async function createPayInWithRetry(amount, description, txIdSource) {
  // Generar la key ANTES del loop — misma en todos los reintentos
  const idempotencyKey = crypto.randomUUID();

  for (let attempt = 1; attempt <= 3; attempt++) {
    const response = await fetch(`${BASE_URL}/v1/br/payin/pix/instant`, {
      method: 'POST',
      headers: {
        ...buildAuthHeaders('POST', '/v1/br/payin/pix/instant', '', bodyString),
        'x-idempotency-key': idempotencyKey,  // ← siempre el mismo
      },
      body: bodyString,
    });

    if (response.ok) return response.json();
    if (response.status === 502 || response.status === 503) {
      await sleep(Math.pow(2, attempt) * 1000);  // backoff exponencial
      continue;
    }
    throw new Error(`Error ${response.status}`);
  }
}