Idempotency and Duplicate Prevention

Not every create API is intrinsically idempotent. Apply a business identifier and recovery strategy before sending a mutation.

Accounts

POST /accounts can create another account for the same uid. Query /users/{uid}/accounts, serialize concurrent provisioning in your backend, and persist the chosen account_id transactionally.

Internal and external withdrawals

Every request uses a globally unique client_request_id. Store it before sending the request and bind it to your order or payout.

If the response is lost:

1. Keep the original client_request_id.
2. Call GET /withdrawals/client-request/{client_request_id}.
3. Persist the returned withdrawal_id and continue status polling.
4. Create a new request only after proving that no original result exists and applying your business policy.

WITHDRAWAL_NOT_FOUND means no record was found at lookup time. The original request may still be processing, so a single 404 does not prove it was never processed. Perform recovery lookups with the original ID at bounded intervals and for a limited number of attempts. If uncertainty persists, stop mutations and contact support with the request and business identifiers. For duplicates or conflicts, compare the original request with the persisted financial intent rather than bypassing the conflict with a new ID.

Do not retry mutations automatically on timeout or HTTP 500. Read-only requests can be retried with bounded exponential backoff when error.action is RETRY_LATER, using fresh HMAC headers each time.

Suggested local record

Store business operation type and ID, client_request_id, request fingerprint, OOLIN resource ID, state, first-attempt time, last-check time, and final result. Enforce a unique constraint on the business operation and request ID.

If the same business ID arrives with a different amount, asset, source account, or destination, reject it as a conflict. One client request ID identifies one immutable financial intent.

Account provisioning has no client_request_id: lock on your customer identifier, query existing accounts, create only if absent, and commit the mapping before releasing the lock.