Idempotency
Guarantee safe, repeatable write operations and prevent duplicate transactions.
In financial infrastructure, operations like payment execution, currency exchange, and ledger postings must never be applied twice. Depa uses the Idempotency-Key HTTP header to prevent duplicate operations caused by client retries or network drops.
Mandatory for Write Operations
The Idempotency-Key header is strongly required on all POST, PUT, and PATCH endpoints that mutate balances, trigger payments, or modify ledger state.
How It Works
- Initial Request: The client generates a unique UUID v4 and sends it in the
Idempotency-Keyheader. Depa processes the request, commits the state changes atomically, and caches the result. - Identical Retry: If the exact same request is received with the same idempotency key, Depa recognizes the key and responds with
429 Too Many Requestsalongside a structured error indicating the operation has already been processed.
Idempotency-Key: 550e8400...
• API validates key hasn’t been processed.
• State mutation is committed atomically.
• Returns 200 OK and caches the response.
Idempotency-Key: 550e8400...
• API detects identical key in cache.
• Operation is NOT executed a second time.
• Returns 429 duplicate warning safely.
HTTP Header Specification
Send the header in all mutating API requests:
POST /v1/accounts/acct_0192a/bank_accounts/ba_8901/fiat_payments
Content-Type: application/json
Authorization: Bearer <your_jwt_token>
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
{
"amount": "25000.00",
"currency": "EUR",
"recipient_iban": "DE89370400440532013000",
"recipient_name": "Acme Holdings GmbH",
"description": "Invoice #8921 Settlement"
}Error Handling: Duplicate Request
If you submit a request with an idempotency key that has already been executed, Depa responds with HTTP status 429 Too Many Requests:
{
"errors": [
{
"code": "idempotency_key_already_processed",
"message": "This request has already been processed"
}
]
}Recovering from Network Timeouts
If your application sends a payment and encounters a connection reset, socket timeout, or 5xx gateway error before receiving a 200 response, do not generate a new idempotency key.
- Retry the exact same request with the original
Idempotency-Key. - If the initial request never reached Depa, it will be executed cleanly.
- If the initial request completed before the timeout, Depa returns the duplicate response, preventing double-debits.
import { randomUUID } from "node:crypto";
async function executePaymentWithRetry(payload: PaymentPayload) {
const idempotencyKey = randomUUID();
for (let attempt = 0; attempt < 3; attempt++) {
try {
const response = await fetch(`${API_URL}/fiat_payments`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": `Bearer ${token}`,
"Idempotency-Key": idempotencyKey,
},
body: JSON.stringify(payload),
});
if (response.status === 429) {
console.warn("Payment was already processed successfully.");
return;
}
if (!response.ok) throw new Error(`HTTP ${response.status}`);
return await response.json();
} catch (err) {
if (attempt === 2) throw err;
await new Promise((r) => setTimeout(r, 1000 * Math.pow(2, attempt)));
}
}
}