:::warning Required, not optional
Every `POST` must carry an `Idempotency-Key` header. A request without one is
rejected with `missing_idempotency_key`.
:::

Networks fail after the server has already done the work. Without an idempotency
key, a retried "reserve a referral code" would hand out a second code to the same
person. With one, the retry returns the original result.

```bash
curl -X POST https://api.proppertrading.com/v1/affiliates/pre-registrations \
  -H "Authorization: Bearer sk_live_a1b2c3d4_9f83c2e15b7a4d6e8091c3f5a7b9d1e2" \
  -H "Idempotency-Key: 8f14e45f-ea0d-4d1f-9c4b-3e11f0f2c0a1" \
  -H "Content-Type: application/json" \
  -d '{"email":"jamie@example.com"}'
```

Use a fresh UUID per logical operation. Reuse the same one for every retry of
that operation.

## What happens

- **Same key, same body** - you get the original response back, byte for byte,
  with an `Idempotent-Replayed: true` header. Including any secret it contained,
  so a retry of a create still gives you the claim code.
- **Same key, different body** - `409 idempotency_key_reuse`. This is a bug in
  the caller, not something to retry.
- **Same key, original still running** - `409 idempotent_request_in_flight`.
  Wait a moment and retry.

Responses are replayable for 24 hours.

:::note Only successful responses are stored
If a request fails, the key is released. You can correct the payload and retry
with the same key. That means a rejected request never blocks you.
:::