> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venlyfinance.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Safe retries with idempotency keys

> Send a unique key with each request so a retry never creates a duplicate.

## Why

You send a request, but the network drops the response before it reaches you. Did it go through? With an idempotency key you can just retry: the same key returns the original result instead of doing the work a second time.

## How it works

Every write takes an `idempotencyKey` — a unique ID you generate, like a UUID — in the request body:

```bash theme={null}
curl --request POST \
  --url https://api.venlyfinance.com/v1/accounts/{senderAccountId}/transfers/crypto \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "receiverAccountId": "c3b2a1f0-9d8c-4e3a-bf21-1a2b3c4d5e60",
    "chain": "BASE",
    "asset": "USDC",
    "amount": 25,
    "idempotencyKey": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }'
```

* The **first** call with a key runs the operation.
* The **same key with the same body** returns that original result — the operation runs once, however many times you retry.

## Two rules

1. Generate **one new key per operation** — each transfer, payment, settlement, reversal, adjustment, and pay-in gets its own.
2. Reuse a key **only to retry that exact call**. For a genuinely new operation, generate a new key.

A key is required on transfers, payment requests (create, settle, reverse, and update), pay-in sessions, and virtual bank accounts.

<Tip>
  Save the key before you send the request. If your process restarts mid-flight, the retry reuses the same key and lands exactly once.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="API conventions" icon="list-check" href="/getting-started/conventions">
    Pagination, versioning, and the shared idempotency rules.
  </Card>

  <Card title="Payment requests" icon="money-check-dollar" href="/guides/finance/payment-requests">
    Reserve, settle, reverse — each with its own key.
  </Card>
</CardGroup>