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-linksPOST /payoutsPOST /verification/submissionsPOST /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 -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
| Case | Response |
|---|---|
| First time | Processed normally. |
| Same key, same body | The original status code and body, with the Idempotent-Replayed: true header. |
| Same key, different body | 422 idempotency_key_reuse |
| The original request is still running | 409 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 -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 -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
// 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));
}
}