ACH Return Codes Explained: R01–R85 and How to Handle Them in Production
Understanding ACH Return Codes
When an ACH (Automated Clearing House) transaction fails, the originating bank receives a return code—a two-character alphanumeric that tells you exactly why the transfer didn't go through. Unlike vague error messages, NACHA-standardized return codes (R01 through R85) are precise, actionable, and critical to building resilient payout systems.
If you're integrating ACH into a fintech platform, marketplace, or payroll system, you need to decode these codes and route them to the right handler—retry, user notification, or alternative payment rail. This article walks through the most common codes and the decision logic your system should implement.
The Big Three: Most Common Returns
R01 – Insufficient Funds
The account has insufficient available balance. This is the most frequent return. Your action: notify the user, suggest they add funds, and optionally retry after 1–3 days if the account typically recovers. Don't retry immediately; the funds won't materialize in minutes.
{
"return_code": "R01",
"reason": "Insufficient funds",
"user_action": "Deposit funds and retry",
"retry_window_hours": 48,
"severity": "recoverable"
}
R03 – No Account / Unable to Locate Account
The account number, routing number, or account type doesn't match any active account at the destination bank. This is permanent. Action: flag for manual review, ask the user to verify their bank details, and don't retry.
R10 – Customer Advises Not Authorized
The account holder called their bank and disputed the transaction, claiming they didn't authorize it. This is a fraud signal or genuine dispute. Action: investigate, contact the user, and consider suspending their account pending resolution.
Secondary Codes Worth Monitoring
| Code | Meaning | Retry? | Timeline |
|---|---|---|---|
| R04 | Reserved | No | N/A |
| R05 | Improper debit entry | No | Contact support |
| R07 | Authorization revoked | No | Permanent |
| R09 | Uncollected funds | Yes | 5–10 days |
| R16 | Account frozen | No | Contact bank |
| R20 | Non-transaction account | No | Wrong account type |
| R29 | Corporate customer advises not authorized | No | Dispute/fraud |
Building Return-Handling Logic
Here's a pattern for decoding returns and deciding the next step:
def handle_ach_return(return_code: str, payout_record: dict) -> dict:
"""
Classify ACH return and recommend action.
Returns: { action, retry_after_hours, notify_user, severity }
"""
recoverable = {'R01', 'R09'} # Insufficient funds, uncollected funds
permanent = {'R03', 'R04', 'R05', 'R07', 'R20'}
fraud_signals = {'R10', 'R29'}
if return_code in recoverable:
return {
'action': 'retry',
'retry_after_hours': 48 if return_code == 'R01' else 240,
'notify_user': True,
'severity': 'warning',
'message': 'Funds unavailable; we'll retry in 2 days.'
}
elif return_code in permanent:
return {
'action': 'fail',
'retry_after_hours': None,
'notify_user': True,
'severity': 'error',
'message': 'Account details invalid. Please update and retry.'
}
elif return_code in fraud_signals:
return {
'action': 'escalate',
'retry_after_hours': None,
'notify_user': False,
'severity': 'critical',
'message': 'Unauthorized claim detected. Manual review required.'
}
else:
return {
'action': 'escalate',
'retry_after_hours': None,
'notify_user': False,
'severity': 'unknown'
}
Integration Checklist
- Webhook parsing: Your ACH processor (Stripe, Plaid, Dwolla, etc.) sends return notifications. Parse the return code from the webhook payload.
-
State machine: Track payout states:
pending→returned→retry_scheduledorfailed. - Audit log: Record the return code, timestamp, and action taken for compliance and debugging.
- User notification: Email or in-app alert for recoverable failures; escalate fraud signals to your risk team.
- Reconciliation: Reconcile returned transactions against your ledger daily.
Key Takeaway
ACH returns aren't failures—they're
Decoding ACH return codes programmatically? The ACH Return Codes API returns the full Nacha R01–R85 set with plain-language descriptions and handling guidance.
Top comments (1)
Not retrying R01 right away is a good call. If the account is still short a few hours later you just rack up more return fees for no gain.