DEV Community

Payout Rail
Payout Rail

Posted on

ACH Return Codes Explained: Handling R01, R03, R10 and Beyond in Production

ACH Return Codes Explained: Handling R01, R03, R10 and Beyond in Production

When an ACH transaction fails, your payout system receives a return code. Unlike HTTP status codes, ACH return codes (R01–R85 per NACHA rules) are cryptic two-character strings that tell you why the debit or credit was rejected. Misinterpreting them costs time, money, and customer trust. This guide decodes the most common codes and shows you how to handle them programmatically.

The Big Three: R01, R03, R10

R01: Insufficient Funds

The account exists and is valid, but the balance is too low. This is temporary and recoverable.

  • When it fires: Real-time or during settlement (T+1 for standard ACH).
  • What to do: Retry after 3–5 business days. The customer may have deposits pending. Log the failure, notify the customer, and queue a retry. 
{
  "return_code": "R01",
  "reason": "Insufficient Funds",
  "action": "retry_after_5_days",
  "customer_notified": true,
  "next_attempt": "2025-01-17T09:00:00Z"
}
Enter fullscreen mode Exit fullscreen mode

R03: No Account / Unable to Locate Account

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

  • When it fires: During OFAC/account validation or settlement.
  • What to do: Do not retry. Ask the customer to verify their bank details. Flag the account as invalid in your database. 
if (returnCode === 'R03') {
  await updatePayoutAccount(accountId, { status: 'invalid', requires_reentry: true });
  await notifyCustomer(customerId, 'Please update your bank account information');
}
Enter fullscreen mode Exit fullscreen mode

R10: Customer Advises Not Authorized

The account holder disputes the transaction—they claim they didn't authorize it or don't recognize your company.

  • When it fires: 10–60 days after settlement (customer disputes).
  • What to do: Investigate immediately. Verify consent records, email confirmations, or signed agreements. If legitimate, respond to the dispute. If not, reverse the payout and halt future attempts. 
if (returnCode === 'R10') {
  const dispute = {
    account_id: accountId,
    return_code: 'R10',
    received_at: new Date(),
    status: 'pending_investigation',
    action_required: 'verify_authorization_records'
  };
  await logDispute(dispute);
  await pausePayouts(customerId);
}
Enter fullscreen mode Exit fullscreen mode

Other Common Codes

Code Reason Recoverable? Action
R02 Account Closed No Update account, ask for new details
R04 Invalid Account Number No Validate format, re-enter
R05 Duplicate Entry Yes Deduplicate, retry with new trace ID
R07 Authorization Revoked No Stop all payouts, contact customer
R09 Uncollected Funds Yes Retry after 5 days
R29 Corporate Customer Advises Not Authorized No Investigate, respond to dispute

Building Robust Return Handling

When your bank sends return files (typically NACHA 094 format), parse the return code and route accordingly:

async function handleACHReturn(returnRecord) {
  const { accountId, returnCode, amount, traceId } = returnRecord;

  const recoverable = ['R01', 'R05', 'R09'].includes(returnCode);

  if (recoverable) {
    // Schedule retry
    await scheduleRetry(accountId, amount, 5); // 5 days
  } else {
    // Permanent failure
    await markAccountInvalid(accountId);
    await routeToAlternateMethod(accountId, amount); // e.g., Visa Direct
    await notifyOps(returnCode, accountId);
  }

  // Log for reconciliation
  await logReturn({
    trace_id: traceId,
    return_code: returnCode,
    handled_at: new Date(),
    next_action: recoverable ? 'retry' : 'manual_review'
  });
}
Enter fullscreen mode Exit fullscreen mode

Key Takeaway

R-codes are not errors—they're signals. R01 and R09 are temporary setbacks; R03, R02, and R04 mean the account data is wrong; R10 and R29 are disputes that require investigation. Build your retry logic around recoverability, not guesswork. Parse returns automatically, log everything, and escalate disputes to your operations team immediately.

The NACHA rulebook defines all 85 codes; familiarize yourself with the full set (available at nacha.org). Your bank

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)