Skip to main content
Idempotency ensures that repeating the same API request produces the same result without creating duplicate resources or triggering duplicate operations. This is especially important for financial transactions, where network issues or timeouts could cause your application to retry a request that already succeeded.

​
How it works

Include an Idempotency-Key header with a UUID v4 value on any POST, PUT, or PATCH request. The API stores the response for that key and returns the cached result if the same key is sent again.
Request with idempotency key
curl -X POST https://api.lumx.io/transactions/on-ramp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "rail": "PIX",
    "sourceCurrency": "BRL",
    "sourceAmount": "10000.00",
    "targetCurrency": "USDC",
    "purpose": "PERSONAL_ACCOUNT"
  }'

​
Behavior

ScenarioResult
First request with a keyProcesses normally and caches the response
Same key, same bodyReturns the cached response with X-Idempotency-Cached: true header
Same key, different bodyReturns a 409 Conflict error
Both successful and failed responses are cached. If the original request failed, retrying with the same key returns the same error.

​
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 UUID v4 for each unique operation. Do not reuse keys across different operations.
  • Store the key before sending the request. If your application crashes mid-request, you can safely retry with the same key.
  • Use idempotency keys on all mutation requests (POST, PUT, PATCH), especially for transactions and customer creation.