Skip to content

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 ​

  1. Make one UUID v4 per operation, for example per order, and store it with the order.
  2. Send it as Idempotency-Key on the write.
  3. On a retry, send the same key and the same body.
  4. The server returns the stored answer with Idempotent-Replay: true and 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:

bash
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"
  }'
js
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();
python
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
<?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

json
{
    "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

json
{
    "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

json
{
    "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

json
{
    "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 ​

js
import { randomUUID } from 'node:crypto';

const key = randomUUID();
python
import uuid

key = str(uuid.uuid4())
php
<?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 ​

AnswerWhat to do
Timeout or connection errorRetry with the same key
5xxRetry with the same key, with backoff
409 IDEMPOTENCY_KEY_IN_FLIGHTWait a second, retry with the same key
409 CONCURRENT_MODIFICATIONTwo 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_LIMITEDWait for Retry-After, retry with the same key
4xx validation errorsFix 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:

  1. Wait a short time, for example 200 ms, then 500 ms, then 1 s.
  2. Send the same request again with the same Idempotency-Key.
  3. 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:

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.

Next steps ​

Escrow, payment services and B2B deals for Indonesian businesses.