Capture API idempotency and retries
Prevent duplicate captures when requests time out, conflict, or need a safe retry.
- For
- Integration developers
- Owner
- Integration engineering
- Outcome
- Retry uncertain requests without creating duplicate customer records.
- Last verified
- 2026-08-30
- Next review
- 2026-11-28
- Status
- supported
POST requests require Idempotency-Key. The key identifies one logical request. Reuse it only when retrying that same logical request.
Create stable keys
- Derive the key from a stable source event or record identifier.
- Keep the key opaque and free of customer names, email addresses, phone numbers, or secrets.
- Use a distinct key for each person in a bulk request.
Handle each result
| Result | Action |
|---|---|
| 2xx | Store the accepted result and do not repeat the logical request. |
| 400 | Correct the request, then use a new key for the corrected logical request. |
| 401 | Repair the client. Do not rotate repeatedly without confirming client ownership. |
| 409 | Inspect the prior result for the same key before deciding whether a new request exists. |
| 429 or 503 | Retry with bounded exponential backoff and the same key. |
| Network timeout | Check for a prior result, then retry the same request with the same key. |
Bound the retry policy
- Set a request timeout that is suitable for the integration.
- Use exponential backoff with random jitter for retryable results.
- Set a maximum attempt count and move unresolved work to a visible failure queue.
- Keep safe request identifiers and final outcome for support.