Cloak API
Idempotency & retries
Send X-Idempotency-Key on every POST /order. A retry carrying the same key returns the original order instead of creating another one.
Without a key
We fall back to the quoteId, so a retry carrying the same quote is still safe. Still send the header so the retry behavior is explicit and under your control.
Reusing a key with different terms
Cloak returns 409 IDEMPOTENCY_CONFLICT. Do not retry it unchanged. Generate one key for each order and reuse it only when retrying that order.
What is safe to retry
| Call | Safe to retry? | Why |
|---|---|---|
| GET | Always | Every read is side-effect free. |
| POST /quote | Always | Quoting does nothing on-chain and costs nothing. |
| POST /order | With a key | The key replays the original response instead of creating a second order. |
| POST /deposit | Always | Idempotent by nature. It is a hint, verified against the chain. |
Retries cannot create two deposits
The idempotency key prevents duplicate orders. Refreshed transactions also represent the same deposit, so only one can succeed. See Refresh a transaction.
Concurrent requests
If two of your workers create the same order concurrently, the loser receives 409 ORDER_IN_PROGRESS. Retry after a short delay to receive the original order. See Errors.