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.

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":"[email protected]"}'

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.

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.