Idempotency
Retry safely without double-resolving an alert.
Networks fail and requests time out. The Idempotency-Key header makes retries
safe: the same request never runs twice.
curl -X POST "https://api.disputely.com/v1/alerts/9XOJYR6WNLMU2XEQMSF244GFI/resolve" \
-H "Authorization: Bearer dspm_live_YOUR_KEY" \
-H "Idempotency-Key: 4f9c2b1e-7a3d-4e8f-9b2a-1c5d6e7f8a9b" \
-H "Content-Type: application/json" \
-d '{ "refundedAmount": 29.97, "refundedCurrency": "USD" }'- Any string between 8 and 128 characters works. A UUID per logical operation is the standard choice.
- On the Merchant API the only endpoint that changes state is
resolve — always send the header
there.
GETrequests ignore it.
How retries behave
| Scenario | What happens |
|---|---|
First request succeeds (or fails with a 4xx) | Result is cached for 24 hours under your key. |
| Retry with the same key and same body | Cached response replayed — no side effect. Idempotent-Replayed: true header added. |
| Retry with the same key but a different body | 409 idempotency_conflict. Pick a new key. |
First request fails with a 5xx (e.g. provider_unavailable) | Not cached — retrying with the same key gets a real re-attempt. |
That last row is why retries converge: if the card network times out, the
resolution may or may not have gone through upstream. Retry with the same key —
if it already went through, resolving an already-RESOLVED alert simply
returns 200 with the current alert.
Don't reuse a key across different operations, and don't put secrets or customer data in the key — it can appear in error responses.