Idempotency and Retries

When originating a transfer through /bank_transfer/create, it is important that Plaid can correctly differentiate distinct requests. The required parameter idempotency_key is used, along with the parameters client_id, amount, account_id, type, and network, to establish the uniqueness of a request.

Any two requests having the same value for these parameters will be treated as the same request and result in only a single transfer. The second request will simply return the transfer created by the first. Plaid guarantees idempotency between requests for at least 7 days after the request was made. As an added level of safety, you may confirm whether a request generated a new transfer by checking the ID returned from the API against your own database.

The idempotency_key alone does not establish uniqueness - this is to support re-use of a single idempotency key across a batch of transfers. For example, debiting a batch of accounts on the first of the month and using the calendar date as your idempotency key, you can be sure to generate separate requests as each transfer targets a different account. The idempotency_key can be used to communicate to Plaid that two similar-looking requests are distinct. For example, in order to originate a transfer for the same amount and account as another transfer, sending a different value for idempotency_key will result in a new transfer.

Although Plaid works to establish a highly reliable service, from time to time the API will be unable to process a request and return an unknown server error (status code 500). In these cases, you should retry the request through the Plaid API only - Plaid ensures that retries with the same parameters (as described in the Idempotency section) will never result in a duplicated transfer. Resubmitting the request through a secondary provider has no such guarantee.

It’s a good idea when retrying requests to use an exponential backoff strategy, as this avoids exacerbating issues caused by resource exhaustion. Retries, along with idempotency, provide an added level of reliability that requests to move money are correctly received and processed by Plaid.