Retries & idempotency
Recover from timeouts and rate limits without duplicating operations.
Use the right operation identity
| Flow | Identity | Retry rule |
|---|---|---|
| Deposit quote | Idempotency-Key: UUID | Reuse the original header and body. |
| Deposit offer | Idempotency-Key + externalId | Reuse both identities and the same body. |
| Withdrawal order | externalId | Reuse the original order ID; the existing accepted order is returned. |
Polling and rate limits
- Prefer signed callbacks to repeated status requests.
- Poll pending deposit quotes at most once every five seconds, with backoff.
- Wallet and withdrawal lookup responses can be cached for up to 30 seconds.
- Honor Retry-After on rate limits and use bounded exponential backoff.
- For FEATURE_NOT_AVAILABLE, confirm account access with support instead of retrying.
Keep callback processing idempotent
Verify signatures before trusting the payload, persist incoming events, and reconcile uncertain state through the corresponding lookup endpoint. Keep deposit and withdrawal payload parsers separate.