Idempotencia

Reintenta sin duplicar cobros ni transferencias con la cabecera Idempotency-Key.

Un timeout o un error de red te deja sin saber si la operación se creó. Con Idempotency-Key puedes reintentar la misma petición sin crear un segundo cobro ni una segunda transferencia.

Dónde es obligatoria

  • POST /payment-links
  • POST /payouts
  • POST /verification/submissions
  • POST /deposit-accounts
  • Alta de beneficiarios y de billeteras.

Si falta, la API responde 400 idempotency_key_required. Usa un valor de 1 a 255 caracteres imprimibles, estable por operación: por ejemplo, el identificador de tu orden.

cURL · POST sin Idempotency-Key
curl -X POST "$CLOBEPAY_API_BASE/payment-links" \
  -H "Authorization: Bearer $CLOBEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":"50.00","orderReference":"10043"}'

Respuesta esperada: HTTP 400

Cómo responde

Comportamiento de Idempotency-Key
CasoRespuesta
Primera vezSe procesa normalmente.
Misma llave y mismo cuerpoMismo código y cuerpo originales, con la cabecera Idempotent-Replayed: true.
Misma llave, cuerpo distinto422 idempotency_key_reuse
La petición original sigue en curso409 idempotency_request_in_progress: reintenta en unos segundos.

Las llaves se guardan 24 horas por comercio. Después, el mismo valor cuenta como nuevo.

cURL · Repetir la misma petición (replay)
curl -i -X POST "$CLOBEPAY_API_BASE/payment-links" \
  -H "Authorization: Bearer $CLOBEPAY_API_KEY" \
  -H "Idempotency-Key: order-10042" \
  -H "Content-Type: application/json" \
  -d '{"amount":"50.00","description":"Pedido 10042","orderReference":"10042","metadata":{"cart_id":"c_77"}}'

Respuesta esperada: HTTP 201

cURL · Misma llave, cuerpo distinto
curl -X POST "$CLOBEPAY_API_BASE/payment-links" \
  -H "Authorization: Bearer $CLOBEPAY_API_KEY" \
  -H "Idempotency-Key: order-10042" \
  -H "Content-Type: application/json" \
  -d '{"amount":"75.00","description":"Pedido 10042","orderReference":"10042"}'

Respuesta esperada: HTTP 422

Reintentos

Node.js · reintentos con la misma llave
// Reintenta errores transitorios con la MISMA Idempotency-Key.
// Retry transient errors with the SAME Idempotency-Key.
const TRANSIENT = new Set([429, 500, 502, 503, 504]);

async function isTransient(res) {
  if (TRANSIENT.has(res.status)) return true;
  if (res.status !== 409) return false;
  const { error } = await res.clone().json().catch(() => ({}));
  return error === 'idempotency_request_in_progress';
}

export async function postWithRetries(url, body, idempotencyKey, attempts = 5) {
  for (let i = 0; ; i++) {
    let res;
    try {
      res = await fetch(url, {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${process.env.CLOBEPAY_API_KEY}`,
          'Idempotency-Key': idempotencyKey,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(body),
      });
    } catch (networkError) {
      if (i === attempts - 1) throw networkError; // resultado incierto / uncertain result
    }
    if (res && (i === attempts - 1 || !(await isTransient(res)))) return res;
    const retryAfterMs = Number(res?.headers.get('Retry-After')) * 1000;
    const backoffMs = Math.min(30_000, 500 * 2 ** i) * (0.5 + Math.random() / 2);
    await new Promise((r) => setTimeout(r, retryAfterMs || backoffMs));
  }
}