DEV Community

Payout Rail
Payout Rail

Posted on

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

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

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

When an ACH transfer fails, your payout system receives a return code. Understanding what each code means—and when it arrives—is the difference between a graceful retry and a broken user experience.

The National Automated Clearing House Association (NACHA) defines 85 return codes (R01 through R85). Each one signals a specific reason why a bank rejected the debit or credit. As a developer integrating payouts, you need to know which codes are recoverable, which are permanent, and how to route around them.

The Big Three: R01, R03, and R10

R01: Insufficient Funds

The account exists and is valid, but the balance is too low. This is temporary in most cases—the account holder may deposit funds later.

How to handle: Retry after 1–3 business days. If it fails again, notify the user and offer an alternate payment method (e.g., Visa Direct or RTP).

R03: No Account / Unable to Locate Account

The routing number and account number don't match any account at that bank. This is permanent.

How to handle: Stop retrying immediately. Flag the account as invalid in your database. Prompt the user to re-enter their banking details or use a different payment rail.

R10: Customer Advises Not Authorized

The recipient claims they never authorized this debit. This is a fraud signal and permanent for that account.

How to handle: Investigate the original authorization. If legitimate, contact the customer directly. Do not retry to the same account. Consider flagging the originator (payer) in your compliance system.

Return Timing and Reconciliation

ACH returns typically arrive within 1–2 business days of the original transaction attempt. However, some codes (like R29 – Corporate Customer Advises Not Authorized) can come back up to 60 days later.

Return Code Description Timing Recoverable?
R01 Insufficient Funds 1–2 days Yes, retry
R03 No Account 1–2 days No, invalid account
R04 Invalid Account Number 1–2 days No, invalid account
R10 Unauthorized 1–2 days No, fraud signal
R29 Corporate Customer Advises Not Authorized Up to 60 days No, dispute
R37 Source Document Presented for Payment 1–2 days No, duplicate

Your reconciliation logic must account for this delay. A payout that appears "pending" may still return days later.

Programmatic Handling: A Pattern

Here's a concrete approach to handling returns:

async function handleACHReturn(returnCode, payoutId) {
  const payout = await db.payouts.findById(payoutId);

  // Classify the return
  const isRecoverable = ['R01', 'R02', 'R21'].includes(returnCode);
  const isFraud = ['R10', 'R29'].includes(returnCode);
  const isInvalidAccount = ['R03', 'R04'].includes(returnCode);

  if (isFraud) {
    await db.payouts.update(payoutId, { status: 'fraud_hold' });
    await notifyCompliance(payout);
    return;
  }

  if (isInvalidAccount) {
    await db.payouts.update(payoutId, { status: 'invalid_account' });
    await notifyUser(payout.userId, 'Please update your bank details');
    return;
  }

  if (isRecoverable) {
    const retryCount = payout.retryCount || 0;
    if (retryCount < 3) {
      await scheduleRetry(payoutId, retryCount + 1);
    } else {
      // After 3 retries, try an alternate rail
      await routeToAlternateRail(payoutId, 'rtp_or_visa_direct');
    }
    return;
  }

  // Unknown code: hold and alert
  await db.payouts.update(payoutId, { status: 'manual_review' });
  await alertOps(`Unknown return code ${returnCode} for payout ${payoutId}`);
}
Enter fullscreen mode Exit fullscreen mode

Key Takeaways

  • R01, R02, R21 (insufficient funds, account closed, unauthorized user): Retry-safe; implement exponential backoff.
  • R03, R04, R05 (invalid/closed account): Permanent; ask the user to update their account.
  • R10, R29 (fraud signals): Escalate immediately; do not retry.
  • Return windows vary: Most

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)