Idempotency

Retry without duplicating payments or payouts using the Idempotency-Key header.

A timeout or a network error leaves you unsure whether the operation was created. With Idempotency-Key you can retry the same request without creating a second collection or a second payout.

Where it is required

  • POST /payment-links
  • POST /payouts
  • POST /verification/submissions
  • POST /deposit-accounts
  • Creating beneficiaries and wallets.

If it is missing, the API returns 400 idempotency_key_required. Use a value of 1 to 255 printable characters, stable per operation: for example, your order identifier.

cURL · POST without 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"}'

Expected response: HTTP 400

How it responds

Idempotency-Key behavior
CaseResponse
First timeProcessed normally.
Same key, same bodyThe original status code and body, with the Idempotent-Replayed: true header.
Same key, different body422 idempotency_key_reuse
The original request is still running409 idempotency_request_in_progress: retry in a few seconds.

Keys are stored for 24 hours per merchant. After that, the same value counts as new.

cURL · Repeat the same request (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"}}'

Expected response: HTTP 201

cURL · Same key, different body
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"}'

Expected response: HTTP 422

Retries

Node.js · retries with the same key
// 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));
  }
}