DEV Community

Payout Rail
Payout Rail

Posted on

ACH Return Codes Explained: R01 to R85 and How to Handle Them in Production

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)
Enter fullscreen mode Exit fullscreen mode

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)

Collapse
 
azharabbas profile image
Azhar Abbas •

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.

Collapse
 
azharabbas profile image
Azhar Abbas •

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.