ACH Return Codes Explained: R01, R03, R10 & How to Handle Them
Understanding ACH Return Codes: A Developer's Guide
When you're building a payout system, ACH returns are inevitable. A customer's bank rejects the transfer, and your code needs to know why—and what to do next. The National Automated Clearing House Association (Nacha) defines over 85 return codes, but most developers encounter a handful repeatedly. This guide covers the most common ones and how to handle them programmatically.
The Big Three: R01, R03, R10
R01 – Insufficient Funds
What it means: The account has fewer funds available than the payout amount at settlement time.
When it fires: ACH debits (pulling money from a customer's account) settle 1–2 business days after submission. By settlement time, the balance has dropped below the transfer amount.
How to handle it:
- Flag the payout as
status: RETURNED - Log the return code and timestamp
- Retry after 3–5 business days (the customer may have deposited funds)
- If retry fails twice, escalate to manual review or notify the user
{
"payout_id": "po_abc123",
"return_code": "R01",
"return_reason": "Insufficient Funds",
"returned_at": "2025-01-15T14:32:00Z",
"retry_count": 0,
"next_action": "retry_in_5_days"
}
R03 – No Account / Account Closed
What it means: The routing number and account number combination doesn't exist, or the account was closed before settlement.
When it fires: During the settlement window (typically T+1 or T+2).
How to handle it:
- Mark the bank account as
status: INVALID - Do not retry the same account
- Require the user to re-verify their banking details before attempting another payout
- Consider this a hard failure unless the user updates their account info
def handle_ach_return(return_code, payout_id, bank_account_id):
if return_code == "R03":
# Hard fail: account doesn't exist
update_bank_account(bank_account_id, status="INVALID")
update_payout(payout_id, status="FAILED_INVALID_ACCOUNT")
notify_user(payout_id, "Your bank account is no longer valid. Please update it.")
return False
return True
R10 – Customer Advises Not Authorized
What it means: The account holder disputes the transaction—they claim they didn't authorize it.
When it fires: Usually 10–60 days after settlement, when the customer contacts their bank.
How to handle it:
- Treat as a chargeback-like event
- Investigate: was the payout legitimately initiated by the user?
- If yes, respond to the dispute with proof (API logs, user consent records)
- If no, it's fraud; lock the account and investigate
def handle_ach_return(return_code, payout_id, user_id):
if return_code == "R10":
# Potential fraud or authorization dispute
payout = get_payout(payout_id)
user = get_user(user_id)
# Log for manual review
log_dispute({
"payout_id": payout_id,
"user_id": user_id,
"amount": payout.amount,
"timestamp": payout.created_at,
"status": "PENDING_INVESTIGATION"
})
# Notify support team
notify_support(f"R10 dispute on payout {payout_id}")
return False
Other Common Codes Worth Knowing
| Code | Meaning | Retry? | Action |
|---|---|---|---|
| R02 | Account Closed | No | Require re-verification |
| R04 | Invalid Routing Number | No | Validate bank details |
| R05 | Unauthorized User / Account Type | No | Confirm account eligibility |
| R07 | Authorization Revoked | No | Contact user |
| R29 | Corporate Customer Advises Not Authorized | No | Escalate immediately |
Building a Robust Return Handler
The pattern is straightforward:
- Receive the return from your ACH provider (via webhook)
- Decode the return code and classify it (hard fail vs. retriable)
- Update your database with the new payout status
- Decide the next action (retry, escalate, notify user)
- Reconcile your ledger
Most ACH providers (Stripe Connect, Plaid, Unit, or direct Nacha operators) deliver returns as webhooks. Parse the return code immediately and update your payout record with immutable proof of
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 (0)