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-linksPOST /payoutsPOST /verification/submissionsPOST /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 -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
| Caso | Respuesta |
|---|---|
| Primera vez | Se procesa normalmente. |
| Misma llave y mismo cuerpo | Mismo código y cuerpo originales, con la cabecera Idempotent-Replayed: true. |
| Misma llave, cuerpo distinto | 422 idempotency_key_reuse |
| La petición original sigue en curso | 409 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 -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 -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
// 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));
}
}