Skip to main content
Idempotency lets you safely retry POST requests without creating duplicates. Send an Idempotency-Key header and Conduit will return the same response for identical retries.

​
When to Use

Use an idempotency key whenever you might retry a request:
  • Network timeouts or client restarts.
  • Users double-clicking “submit”.
  • Automatic retries from your job queue.
Currently, keys are honored on POST /transactions. Check each endpoint’s reference page as coverage expands.

​
Make an Idempotent Request

curl --request POST https://api.conduit.financial/transactions \
  --header "X-API-Key: your_api_key" \
  --header "X-API-Secret: your_api_secret" \
  --header "Content-Type: application/json" \
  --header "Api-Version: 2024-12-01" \
  --header "Idempotency-Key: unique-key-12345" \
  --data '{"type":"deposit","amount":"100.00","asset":"USD"}'
Guidelines:
  • Generate a fresh key per operation (UUIDs or timestamp + intent work well).
  • Reuse the same key only when retrying the same request payload.
  • Keep keys ≤ 128 characters and store them on the client so you can retry with the original value.

​
What Happens

  1. Conduit processes the first request, stores the response, and returns it.
  2. A retry with the same key and payload returns the cached response plus Idempotency-Replayed: true.

​
Common Errors

  • 422 Unprocessable Entity – The same key was used with different payload data. Pick a new key.
  • 409 Conflict – Two identical requests arrived at the same time. Retry once the first finishes.
  • 400 Bad Request – Key longer than 128 characters; trim the value.

​
Scoping Rules

Keys are unique per client. Two different clients can reuse the same value, but a single client cannot reuse a key for different operations.

​
Retry Tips

Wrap idempotent calls in a retry helper that:
  • Uses the same key for each retry attempt.
  • Backs off when you receive 409 Conflict.
  • Switches to a new key only when the operation truly changes.