---
title: "How do idempotency keys work?"
description: "Send a unique idempotency key with a request so a retry can't create a duplicate. Reusing a key returns the original result instead of acting twice — essential for payouts."
url: "/docs/developers/how-do-idempotency-keys-work/"
category: "Developers"
---

An **idempotency key** is a unique value you attach to a request so that if you send it more than once — after a timeout or a network retry — Fynex acts on it **only once**. Reusing the same key returns the result of the original request instead of creating a duplicate. This matters most for **payouts**, where a duplicate would move money twice.

## How to use it

- **Generate a unique key per action** (for example a UUID) and send it with the request.
- **Reuse the same key** when you retry the same action after an uncertain response (a timeout, a dropped connection). Fynex recognises it and returns the original outcome.
- **Use a new key** for a genuinely new action — a new key means a new payout.

## What Fynex enforces

- **Payouts require an idempotency key**, scoped to your account. If you resend the same key, you'll get back the existing payout rather than a second one — the error you'd see for a clashing reuse is *"payout with this idempotency key already exists"*.
- **Checkout sessions are idempotent** too — the same key won't open a duplicate session.

## Why it matters

When a request times out you often can't tell whether it succeeded. Without an idempotency key, retrying risks a double payout; with one, retrying is safe — worst case you get the same result back. Always retry payout and checkout calls with the original key rather than a fresh one.

## Related

- [Payout statuses and failure codes reference](/docs/developers/payout-statuses-and-failure-codes-reference/)