Skip to main content
Idempotency ensures that retrying a request doesn’t create duplicate side effects. This is critical for financial operations like deposits and withdrawals where a duplicate could move money twice.

​
How it works

  1. Generate a unique Idempotency-Key for each distinct operation
  2. Include it in the request header
  3. If you retry the same request with the same key, Bluum returns the original response instead of processing it again
curl -X POST "$BASE_URL/accounts/$ACCOUNT_ID/deposits" \
  -H "Authorization: Basic $AUTH" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: dep-abc123-unique-id" \
  -d '{
    "amount": "5000.00",
    "currency": "USD",
    "method": "ach",
    "plaid_options": {
      "item_id": "item_abc123",
      "account_id": "acc_1234567890"
    }
  }'

​
When to use idempotency keys

OperationRequiredWhy
DepositsYesPrevent duplicate fund transfers
WithdrawalsYesPrevent duplicate disbursements
OrdersRecommendedPrevent duplicate trades (use client_order_id as alternative)
Account creationOptionalAccount uniqueness is enforced by other means
Read operations (GET)Not neededGETs are naturally idempotent

​
Generating keys

Use any unique string. Common approaches: 
// UUID
const key = crypto.randomUUID();
// dep-550e8400-e29b-41d4-a716-446655440000

// Prefixed with operation type
const key = `dep-${crypto.randomUUID()}`;

// Derived from business logic (user + operation + timestamp)
const key = `dep-${userId}-${Date.now()}`;

​
Behavior

ScenarioResult
First request with keyProcessed normally, response stored
Retry with same key, same bodyOriginal response returned (no reprocessing)
Retry with same key, different bodyError — key is already associated with a different request
Different key, same bodyProcessed as a new request (potential duplicate)

​
Key expiration

Idempotency keys expire after 24 hours. After expiration, the same key can be reused for a new request.

​
Best practices

  • Generate a new key for each distinct operation — don’t reuse keys across different deposits or withdrawals
  • Store the key alongside your local transaction record for debugging
  • Use the key consistently across retries of the same operation
  • Include the operation type in the key prefix for readability (dep-, wdr-)