Errors and returns
Troubleshooting common errors and ACH returns
Overview
ACH returns and Transfer errors can both require investigation and troubleshooting.
An ACH return means that your attempted ACH transfer was returned. This typically not due to a Plaid issue and instead is caused by a problem with the ACH transfer itself, such as alleged fraud, insufficient funds, or a closed account. For more details, see ACH Returns.
A Transfer error is an error from the Plaid Transfer API. Transfer errors are related to your interaction with the Plaid API. Causes may include bank API downtime, exceeding Plaid's limits for transfer activity, or attempting to use a Plaid Transfer feature you haven't been enabled for. For more details, see Transfer errors.
ACH returns
After an ACH 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 debit transfer results in an ACH return, the funds will be automatically clawed back in a return sweep. If a credit transfer experiences an ACH return, the funds will be returned to your Ledger available balance.
Note that an ACH return is distinct from an ACH reversal. An ACH reversal is performed only to correct an erroneous transfer and will only be done at the request of the originator (i.e. you). For details, see Requesting a reversal.
If an ACH transfer is returned, its status will be returned
. 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 return codes, 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 structure is valid, but the account number does not correspond to an existing account, or the name on the transaction does not match the name on the account. | Prompt the user to link another account via Plaid Link and use this newly linked account to create the transfer. |
R09 | Uncollected funds | Available balance is sufficient, but the collected balance is not sufficient to cover the entry | Retry the transaction a few days later after any large "holds" on the user's account have been released. |
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. |
A returned transfer can be retried up to 2 times. When you try to reprocess a returned transfer, the description
field in your /transfer/create
request must be "Retry 1"
or "Retry 2"
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.
ACH return categories
ACH return rates are broken into three categories.
Administrative: The transfer could not be processed due to a technical error with the account. Common return codes in this category include R02 (account closed), R03 (no account), and R04 (invalid account number).
Unauthorized: The transfer was reported as unauthorized. Common return codes in this category include R10 (customer advises originator is not authorized to debit account), R11 (customer advises originator is authorized to debit account, but amount is incorrect), and R07 (customer advises authorization to debit account was revoked).
Other: All other returns. The most common code in this category is R01 (insufficient funds).
Return rate limits
You can view your current return rates by category on the Transfer Dashboard. Plaid's maximum limits for ACH return rates are:
- Overall: 12%
- Administrative: 2.5%
- Unauthorized: 0.4%
If you exceed these limits in a 30 day period, you will be contacted by Plaid with a warning email. Failure to reduce return rates below these limits within three months may result in a fine. If excessive return rates remain unaddressed for an extended period of time, your access to Plaid Transfer may be revoked. If you are having trouble reducing your return rates below these limits, contact your Plaid Account Manager for help.
RTP failures
Plaid performs various checks within /transfer/authorization/create
to fail upfront and as early as possible if the RTP or FedNow transfer won't succeed. However, due to the asynchronous nature of the RTP and FedNow payment networks, it is still possible for transfers to fail after authorization due to a rejection by the receiving bank or an issue in the payment network. Failures in the real-time networks are fairly rare (<1%), and often indicate that the consumer bank account itself is in an unusable state.
If the RTP transfer failed, the status will be failed
and an error code will be present in the return_code
transfer property. For the following failure codes, further attempts to use this bank account for payouts via the real-time network are unlikely to succeed. Instead, we recommend that you prompt your user to link a different bank account via Plaid Link.
Return Code | Description | Notes |
---|---|---|
AC03 | Creditor account is invalid | Account number is not recognized as valid by the receiving bank. |
AC04 | Account closed | The account is closed and no longer active. |
AC06 | Account is blocked | Receiving bank has placed a block on the account, for various operational or legal reasons. |
E997 | Timeout clock has expired | The timeout for processing this transaction was exceeded in the FedNow network. You can safely retry the payment with a different idempotency key. |
Transfer errors
For error codes specific to transfer and accompanying troubleshooting steps, including for common errors TRANSFER_LIMIT_REACHED, TRANSFER_ACCOUNT_BLOCKED, and TRANSFER_FORBIDDEN_ACH_CLASS see Transfer error codes.
Handling 500 errors in transfer creation
You may occasionally 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 use the idempotency_key
field in /transfer/authorization/create
so that retries in this scenario are safe to perform and will not result in duplicate authorizations. Retrying /transfer/create
with the same authorization_id
is guaranteed to only ever produce a single transfer.
Whether 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.
Another way to determine if a transfer creation succeeded after receiving a 500 error from /transfer/create
is to follow up with a call to /transfer/get
using the authorization_id
you received from /transfer/authorization/create
. If the transfer was actually created, you will receive a successful response containing the transfer details. If it wasn't, you will receive a 404 HTTP error with the NOT_FOUND
error code.
Investigating ACH transfers
In the event of a problem with an ACH transfer, you can request that Plaid conduct an investigation. Typical reasons to request an investigation include:
- You accidentally submitted an erroneous transfer
- Your end-customer claims that they did not receive funds you sent them
- Your end-customer claims that you made an unauthorized debit from their account
A fee may be charged for the investigation. For questions regarding the fee structure, contact your Account Manager. The different types of ACH investigations are outlined below.
Requesting a reversal
If you have accidentally submitted an erroneous transfer, you can ask Plaid to initiate a reversal request on your behalf. A reversal can only be done for erroneous transfers. To qualify, it must meet one of the following criteria:
- Transfer is a duplicate of transfer that was previously originated.
- Transfer to or from a customer different from the intended customer to be credited or debited.
- Transfer for an amount different from what was intended.
- Debit transfer originated on a date earlier than the customer was intended to be debited, or credit transfer on a date later than the customer was intended to be credited.
The request must be received in time to be processed within five (5) business days of the original transfer settlement date. To initiate this request, send an email to transfer-ach-operations@plaid.com. Indicate in the subject line that this is an Urgent Reversal Request. Your request must include the following information:
- Transfer ID (if applicable, provide the original and duplicate)
- Dollar amount
- The reason for the request (choose one from the four criteria listed above)
- The reason the erroneous transfer occurred
Note that by requesting a reversal, you agree to hold Plaid harmless from any losses that result from the reversal request.
If your transfer does not qualify for a reversal, because more than five days have passed or it does not meet one of the four criteria, you can request a recall instead.
If you discover the error before your transfer has been submitted by Plaid to the payment network, you should attempt to cancel the transfer instead.
Requesting a trace
If your end customer claims non-receipt of funds, your first step should be to direct them to contact their bank directly to find out where the funds are. If their bank cannot locate the funds, you can contact Plaid to initiate a Trace Request on your behalf.
In order to initiate this request, email transfer-ach-operations@plaid.com. Indicate in the subject line that this is a trace request. Your request must include the following information:
- Transfer ID
- Dollar amount of the transfer
- Settlement date of the transfer
- The reason for the request
Upon receipt of all information needed, Plaid will initiate the request within 2 business days. Once our Banking Partner confirms that the Trace Request has been initiated, we will provide an update. Trace Requests are not required to be responded to within a specific timeframe, but RDFIs generally respond within five business days. If the RDFI is unable to confirm receipt of funds, we recommend proceeding with a Recall Request.
Requesting a recall
A debit or credit transaction initiated by an Originator can be recalled through the ACH network. Before requesting a recall, verify that the following requirements are met:
- The original transaction has not been returned.
- The transaction must be for $1,000.00 or more, or the number of transactions must total $1,000.00 or more to the same end-customer bank account.
Typically, a recall should only be requested if the transaction cannot be cancelled, refunded or reversed.
To initiate a request for a recall, email transfer-ach-operations@plaid.com. Indicate in the subject line that this is a recall request. Your request must include the following information:
- The transfer ID(s):
- Dollar amount of transfer(s)
- The reason for the recall
- The settlement date of the original transaction
Once this information is received, Plaid will send you a Recall Form to complete and return to Plaid.
RDFI response times will vary depending on the financial institution. An RDFI is not obligated to respond to Plaid's request to recall funds. It is possible that if they do respond, and agree to return the funds, the full amount of the original transaction will no longer be available.
A follow-up on the status of your recall will be provided periodically.
Requesting a Written Statement of Unauthorized Debits
In the event that an unauthorized debit return is received within the allowed timeframe, Plaid cannot contest it via the ACH network, but we can help you obtain additional details by requesting a copy of the Written Statement of Unauthorized Debit (WSUD) from the RDFI. This WSUD can then be used as part of your own processes, such as evaluating whether the claim is valid or persuing other avenues for recouping funds. The WSUD will state who owns the account, why a debit was returned, and the date of the WSUD.
To initiate a request for the WSUD, email transfer-ach-operations@plaid.com and provide the following information:
- Transfer ID(s)
- Dollar amount(s)
The RDFI is obligated to provide Plaid with a copy of the WSUD within 10 business days.