Idempotency

Safely retry API requests without creating duplicate operations.

Idempotency ensures that retrying a request returns the same result as the original call without processing the operation again. This prevents duplicate payments, transfers, or other state-changing actions caused by network failures or timeouts.

To make a request idempotent, include a unique Idempotency-Key header. Use a UUID generated once per operation, not per retry.

curl -X POST https://api.devdraft.ai/v0/payment-intents/stablecoin \
  -H "x-client-key: <YOUR_KEY>" \
  -H "x-client-secret: <YOUR_SECRET>" \
  -H "Idempotency-Key: <UUID>" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Scenario	Behaviour
Retry with same key, same params	Returns cached original response (no duplicate created)
Retry with same key, different params	Returns 409 Conflict because the key is already bound to original params
Retry after key expires (24 hours)	Treated as a new request and a new operation is created

Idempotency applies to all state-changing endpoints: payment intents, transfers, and webhooks. GET requests are inherently idempotent and do not require a key.

Generate a fresh UUID for each distinct operation. Reusing a key across different operations will result in a conflict error.