ACH Return Codes Explained: R01 to R85 and How to Handle Them in Production
Understanding ACH Return Codes
When a bank rejects an ACH transaction, it sends back a standardized return code. These codes—defined by Nacha (the National Automated Clearing House Association)—tell you exactly why a transfer failed. Unlike generic "declined" messages, ACH returns are deterministic: the same code always means the same thing, and your handling logic should reflect that.
As a developer building payment systems, you need to decode these codes and route them to the right recovery path: retry, notify the user, switch payment rails, or escalate to compliance.
The Major ACH Return Codes
Here are the codes you'll encounter most often in production:
| Code | Meaning | Recovery Path |
|---|---|---|
| R01 | Insufficient funds | Retry later or ask user to top up |
| R03 | No account / account closed | Mark account invalid; use alternate |
| R04 | Invalid account number | Verify routing + account; flag as bad |
| R05 | Account frozen | Contact user; escalate to support |
| R07 | Authorization revoked | User must re-authorize or use new account |
| R10 | Customer advises not authorized | Fraud signal; escalate immediately |
| R11 | Check digit error | Verify routing/account format |
| R20 | Non-transaction account | Account type incompatible with ACH |
| R29 | Corporate account closed | Mark account closed; notify user |
| R31 | Permissible return entry (CCD only) | Retry with different entry code |
The full Nacha ruleset defines R01–R85. Focus on R01, R03, R04, R05, R07, R10, R11, R20, and R29 first; they cover ~85% of real-world returns.
Handling Returns Programmatically
When your ACH processor (Stripe, Plaid, FedNow, or your bank's API) notifies you of a return, capture the code and timestamp. ACH returns typically arrive 1–5 business days after the original debit.
def handle_ach_return(return_event):
code = return_event['return_code'] # e.g., 'R01'
payout_id = return_event['payout_id']
timestamp = return_event['returned_at']
if code in ['R01']: # Insufficient funds
# Retry in 2–3 days or notify user
schedule_retry(payout_id, delay_days=3)
notify_user(f"Payout failed due to low balance. Retrying {delay_days} days.")
elif code in ['R03', 'R04', 'R20', 'R29']: # Account invalid/closed
# Mark account as unusable; offer alternate
mark_account_invalid(payout_id)
notify_user("Your bank account is no longer valid. Add a new one.")
elif code in ['R05', 'R07']: # Frozen or revoked
# Require user action
escalate_to_support(payout_id)
notify_user("Your account requires manual review.")
elif code == 'R10': # Unauthorized
# Fraud signal; investigate
log_fraud_alert(payout_id)
freeze_account(payout_id)
else:
# Fallback: log and notify ops
log_unknown_return(code, payout_id)
Retry Logic and Timing
- R01 (insufficient funds): Safe to retry after 2–3 business days. The user may have deposited funds.
- R03, R04, R20, R29 (invalid/closed account): Do not retry. Route to an alternate payment method (another bank account, card, or wire).
- R05, R07 (frozen/revoked): Require user intervention. Do not auto-retry.
- R10 (unauthorized): Treat as fraud. Freeze the account and escalate.
Switching Rails on Return
If ACH fails and you have a fallback, consider RTP (Real-Time Payments) or Visa Direct:
- RTP: Settles in seconds, no returns (immediate confirmation or decline). Cost: $0.10–$0.50 per transaction. Best for time-sensitive payouts.
- Visa Direct: Settles in minutes, reversible within 120 days. Cost: $0.50–$2.00. Best for high-value or recurring payouts.
- ACH: Settles in 1–2 days, returnable for 5 days. Cost: $0.01–$0.25. Best for bulk, low-cost payouts.
When an ACH return fires, log it, notify the user, and offer to retry via RTP or
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 (2)
Small catch in the R01 snippet: delay_days is only passed to schedule_retry, so the f-string in notify_user would throw a NameError. Also worth treating R10 separately from the others since it can trigger a dispute flow.
Worth adding a retry cap for R01. Nacha only lets you re-present an entry twice after a return for insufficient funds, so the retry logic shouldn't loop forever.