Errors and Troubleshooting
Common errors and troubleshooting tips
Returns
After a payment has been posted, it can be returned and clawed back from your account for a number of reasons. For example, a bank could determine that there are insufficient funds to complete the transfer, or a consumer can contact their bank and flag the transaction as unauthorized. If a transfer results in an ACH return, the funds will be automatically clawed back in a return sweep.
If a transfer returns, its status in the events API will be returned.
Return types and descriptions
All returned ACH transactions will have an ACH return code. By reading the code, you can troubleshoot returned transactions. For a full list of ACH errors, see ACH Return Codes.
RETURN CODE | DESCRIPTION | NOTES | TROUBLESHOOTING |
|---|---|---|---|
| R01 | Insufficient funds | Available balance is not sufficient to cover the dollar amount of the debit entry. | If you are submitting the transfer on a Friday, we recommend using Same-Day ACH to decrease the likelihood of the user's account balance dipping below the transfer amount over the weekend. |
| R03 | No account or unable to locate account | The account number does not correspond to the individual identified in the entry or a valid account. | Prompt the user to link another account via Plaid Link and use this newly linked account to create the transfer. |
| R10 | Customer advises not authorized | Member advises not authorized, notice not provided, improper source document, or amount of entry not accurately obtained from source document. | Make sure you add proper WEB debit authorization language to your "pay with bank" UX to protect against exposure of returns of over 60 days. Unlike other ACH return codes, you cannot resubmit a payment after encountering an R10 error. |
When you try to reprocess a returned transfer, the description field in your /transfer/create request must be "retry" to indicate that it's a retry of a previously returned transfer. Note that retries are only allowed for transfers returned as R01 or R09.
Error codes
For a list of error codes specific to transfer, and their meaning, see Transfer error codes.
Handling 500 errors in transfer creation
Due to unexpected circumstances, you may rarely encounter a 500 HTTP error when creating a transfer via /transfer/authorization/create or /transfer/create. In this case, it's possible that the authorization or transfer was created successfully, but the response was not received. It is highly recommended to utilize the idempotency_key field in /transfer/authorization/create so that retries in this scenario are safe to perform and will not result in a duplicate authorizations. Retrying /transfer/create with the same authorization_id is guaranteed to only ever produce a single transfer.
Rather you retry the request to /transfer/create or not, it's possible that the first request succeeded, and so your integration should be prepared to consume events from /transfer/event/sync that you may not have seen the transfer_id for previously. It is recommended you have a recovery process in place, either by logging these instances for manual review and reconciliation, or automatically reconciling by pulling the transfer details via /transfer/get and using the transfer.metadata property to utilize any client-side data you attached to the transfer for reference.