Idempotency & Replay Protection

POST operations that create a resource, change a resource lifecycle, or move money accept an optional Idempotency-Key header so a retried request cannot create a second object, apply a status transition twice, or move money twice.

Idempotency-Key: 8f1c2e3a-4b5d-6e7f-8091-a2b3c4d5e6f7

The header is always optional. Omitting it does not fail the request. Generate a unique key per logical operation when you may retry. A UUID is a good default. Send the same key when retrying after a network error, 429, or 500.

Replay window

Keys are retained for 24 hours per API key. Within that window:

• The same method, path, and body with the same key returns the original HTTP status and payload.
• The same key with a different body returns 409 with code idempotency_conflict and param Idempotency-Key.
• Concurrent in-flight requests that share a key are serialized: one executes, the others wait for that result or receive 409 / idempotency_conflict.

After 24 hours the key may be reused as a new operation.

Safe methods (GET, HEAD) ignore the header.

Example

curl https://api.rookpayments.com/v1/cards \
  -X POST \
  -H "Authorization: Bearer rk_live_..." \
  -H "X-Program-ID: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Idempotency-Key: 8f1c2e3a-4b5d-6e7f-8091-a2b3c4d5e6f7" \
  -H "Content-Type: application/json" \
  -d '{"wallet_id":"7c9e6679-7425-40de-944b-e07fc1f90ae7"}'