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

# Idempotency

> Retry any write safely — every mutating endpoint honors idempotency keys.

**Every mutating endpoint (POST, PUT, PATCH, DELETE) honors idempotency keys
uniformly.** Send an `Idempotency-Key` header (the `X-Idempotency-Key`
spelling is accepted as an alias) to retry any write without creating
duplicates.

```bash theme={null}
curl -X POST "https://api.hyperprop.com/platform/v1/organization/trading-accounts" \
  -H "X-API-Key: hp_live_your_key_here" \
  -H "Idempotency-Key: order-8814-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{"type": "evaluation", "tradingPlanId": "...", "traderId": "..."}'
```

## How it works

* The key is scoped to **your organization + the request path**. The first
  request with a given key executes normally and its response is cached for
  **24 hours**.
* A replay (same key, same path) within 24 hours returns the cached response
  with an `Idempotency-Replayed: true` response header — the operation is
  **not** executed again.
* If a request with the same key is still in flight, the duplicate gets
  `409 IDEMPOTENCY_KEY_IN_PROGRESS` — back off and retry; you'll then receive
  the cached response.
* **5xx responses are not cached**, so retrying after a server error
  re-executes the request — that's what you want. 2xx–4xx responses are
  cached; if a request failed validation and you fix the payload, use a
  **fresh key**.
* Keys are free-form strings up to 255 characters. Use something that
  identifies the operation on your side, for example `order-8814-attempt-1`.

## Scope

This applies to account creation, account PATCH (status, `currentBalance`,
metadata), rules, plans, lockouts, payouts, team, webhooks — every write on
the platform API. Payouts additionally forward the key to the trade engine
for engine-level double-withdrawal protection.


## Related topics

- [Errors](/concepts/errors.md)
- [Rate limits & quotas](/concepts/rate-limits.md)
- [Quickstart](/quickstart.md)
- [Execute a payout (balance withdrawal)](/platform-api/organization/execute-a-payout-balance-withdrawal.md)
- [Changelog](/changelog.md)