Idempotency and retries
A request can time out after the server already did the work. If you simply send it again, you may create a second escrow or a second payout instruction. The Idempotency-Key header prevents that: the server remembers the first answer for that key and returns it again.
How it works
- Make one UUID v4 per operation, for example per order, and store it with the order.
- Send it as
Idempotency-Keyon the write. - On a retry, send the same key and the same body.
- The server returns the stored answer with
Idempotent-Replay: trueand does nothing else.
Keys are kept for 24 hours and are scoped to the user, the API key, the workspace, the method and the exact path, so the same key on another route or another resource (say a different milestone) is a different operation. Only POST, PUT, PATCH and DELETE use the header; a GET ignores it and always returns fresh data. Requests without the header work as normal.
A real replay
The first call creates a payout instruction:
curl -X POST https://api.rekberpay.com/v1/enterprise/payout-instructions \
-H "Authorization: Bearer $REKBERPAY_WORKSPACE_KEY" \
-H "Idempotency-Key: fffffffa-ffff-4fff-8fff-ffffffffffff" \
-H "Content-Type: application/json" \
-d '{
"label": "Lotus Print House main account",
"currency": "IDR",
"bank_name": "Bank Mandiri",
"account_number": "1230004567",
"account_holder": "CV Lotus Print House",
"country_code": "ID"
}'const res = await fetch('https://api.rekberpay.com/v1/enterprise/payout-instructions', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.REKBERPAY_WORKSPACE_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': 'fffffffa-ffff-4fff-8fff-ffffffffffff',
},
body: JSON.stringify({
label: "Lotus Print House main account",
currency: "IDR",
bank_name: "Bank Mandiri",
account_number: "1230004567",
account_holder: "CV Lotus Print House",
country_code: "ID"
}),
});
const data = await res.json();import os
import requests
resp = requests.post(
"https://api.rekberpay.com/v1/enterprise/payout-instructions",
headers={
"Authorization": f"Bearer {os.environ['REKBERPAY_WORKSPACE_KEY']}",
"Idempotency-Key": "fffffffa-ffff-4fff-8fff-ffffffffffff",
},
json={
"label": "Lotus Print House main account",
"currency": "IDR",
"bank_name": "Bank Mandiri",
"account_number": "1230004567",
"account_holder": "CV Lotus Print House",
"country_code": "ID",
},
timeout=30,
)
print(resp.status_code, resp.json())<?php
$ch = curl_init('https://api.rekberpay.com/v1/enterprise/payout-instructions');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('REKBERPAY_WORKSPACE_KEY'),
'Content-Type: application/json',
'Idempotency-Key: fffffffa-ffff-4fff-8fff-ffffffffffff',
],
CURLOPT_POSTFIELDS => json_encode([
'label' => 'Lotus Print House main account',
'currency' => 'IDR',
'bank_name' => 'Bank Mandiri',
'account_number' => '1230004567',
'account_holder' => 'CV Lotus Print House',
'country_code' => 'ID',
]),
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);201 Created
{
"success": true,
"data": {
"id": "1111111b-1111-4111-8111-111111111111",
"label": "Lotus Print House main account",
"counterparty": null,
"currency": "IDR",
"bank_name": "Bank Mandiri",
"account_number_masked": "1230****67",
"account_holder": "CV Lotus Print House",
"country_code": "ID",
"status": "pending_review",
"signed": true,
"verified_at": null,
"created_at": "2026-10-13T14:33:17.344Z",
"updated_at": "2026-10-13T14:33:17.344Z"
}
}The same call again, with the same key and body, returns the same instruction and does not create a second one:
201 Created with Idempotent-Replay: true
{
"success": true,
"data": {
"id": "1111111b-1111-4111-8111-111111111111",
"label": "Lotus Print House main account",
"counterparty": null,
"currency": "IDR",
"bank_name": "Bank Mandiri",
"account_number_masked": "1230****67",
"account_holder": "CV Lotus Print House",
"country_code": "ID",
"status": "pending_review",
"signed": true,
"verified_at": null,
"created_at": "2026-10-13T14:33:17.344Z",
"updated_at": "2026-10-13T14:33:17.344Z"
}
}Mistakes the server catches
The same key with a different body:
422 Unprocessable Entity
{
"success": false,
"error": {
"code": "IDEMPOTENCY_KEY_CONFLICT",
"message": "Idempotency key reused with a different request body."
}
}A key that is not a UUID v4:
400 Bad Request
{
"success": false,
"error": {
"code": "IDEMPOTENCY_KEY_INVALID",
"message": "Idempotency-Key must be a UUID v4."
}
}A retry while the first call with that key is still running answers 409 IDEMPOTENCY_KEY_IN_FLIGHT. Wait a moment and retry with the same key.
Making keys
import { randomUUID } from 'node:crypto';
const key = randomUUID();import uuid
key = str(uuid.uuid4())<?php
function uuidv4(): string
{
$data = random_bytes(16);
$data[6] = chr(ord($data[6]) & 0x0f | 0x40);
$data[8] = chr(ord($data[8]) & 0x3f | 0x80);
return vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($data), 4));
}
$key = uuidv4();The key must be a real version 4 UUID: the third group starts with 4 and the fourth with 8, 9, a or b. A hash cut into UUID shape is refused with 400 IDEMPOTENCY_KEY_INVALID. Generate the key once, store it next to your order, and reuse it for every retry of that order.
Retrying safely
| Answer | What to do |
|---|---|
| Timeout or connection error | Retry with the same key |
5xx | Retry with the same key, with backoff |
409 IDEMPOTENCY_KEY_IN_FLIGHT | Wait a second, retry with the same key |
409 CONCURRENT_MODIFICATION | Two changes met on the same deal, milestone or counterparty. Wait a moment and retry with the same key. See below |
Any other 409 (NOT_DRAFT, FEE_NOT_AGREED, INVALID_STATE) | The state does not allow it. Read the resource and decide. Do not retry blindly |
429 RATE_LIMITED | Wait for Retry-After, retry with the same key |
4xx validation errors | Fix the request. A new body needs a new key |
CONCURRENT_MODIFICATION
When two writes change the same deal, milestone or counterparty at the same moment, one of them is refused whole and answers 409 CONCURRENT_MODIFICATION. It is retryable: nothing was changed, and a failed answer never uses up the idempotency key (only successful answers are stored). So:
- Wait a short time, for example 200 ms, then 500 ms, then 1 s.
- Send the same request again with the same
Idempotency-Key. - After three tries, read the resource. The other change may have already put it in the state you wanted (for example the milestone is already
funded). If so, treat your request as done. If not, decide again from what you read.
The message tells the two causes apart. "Another change to the same deal or counterparty was being saved at the same moment ... Try again." is a pure collision: retry. "This item changed. Reload and try again." means the status moved under you: read it first, and only then retry.
A retry loop in Node.js:
async function postWithRetry(url, body, apiKey, idempotencyKey, attempts = 5) {
for (let i = 0; i < attempts; i += 1) {
try {
const res = await fetch(url, {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
'Idempotency-Key': idempotencyKey,
},
body: JSON.stringify(body),
});
if (res.status === 429) {
await new Promise((r) => setTimeout(r, Number(res.headers.get('retry-after') ?? 1) * 1000));
continue;
}
if (res.status >= 500) {
await new Promise((r) => setTimeout(r, 2 ** i * 500));
continue;
}
if (res.status === 409) {
const code = (await res.clone().json().catch(() => null))?.error?.code;
if (code === 'IDEMPOTENCY_KEY_IN_FLIGHT' || code === 'CONCURRENT_MODIFICATION') {
await new Promise((r) => setTimeout(r, 2 ** i * 500));
continue;
}
}
return res;
} catch {
await new Promise((r) => setTimeout(r, 2 ** i * 500));
}
}
throw new Error('Gave up after retries; the same key is still safe to use later');
}Where it is supported
These writes honour the header: escrows (create, from-link, join, status changes, shipping, tracking, chat), payments, Jasa Pembayaran, withdrawals, and the enterprise deals, milestones, approvals, releases, live milestone payments and manual payment claims, payout instructions, the default fee allocation, fee agreements and evidence or disputes on shared deals, business verification submit, templates, notes, API key revocation and webhook changes. Ratings, notifications, uploads, documents, counterparties, partner links, members and settings do not use it. Each endpoint in the API reference states it under Idempotency. Two writes skip it on purpose because their answer holds a secret that must not be stored: creating a workspace API key, and adding a webhook or rotating its secret.