Subscribe to your ACH originator or bank API's return webhook or poll for return entries; parse the return reason code from the addenda record
Classify codes into three buckets: hard failures that require no retry (R02 account closed, R03 no account, R04 invalid account number, R07/R10 authorization revoked), soft failures that may retry once (R01 insufficient funds, R09 uncollected funds), and administrative codes requiring data correction (R04, R05, R08)
For R01/R09 soft failures, implement a single retry no sooner than 1 banking day later; NACHA rules prohibit retrying an NSF return more than 2 times on the original authorization
For R07, R10, R29, and R23 codes that indicate authorization revoked or not authorized, immediately stop all future debits on that account and notify the customer; do not retry
For R11 (check truncation entry return) and R14/R15 (representative payee deceased/unable), treat as requiring human review before any further action
Known gotchas
R10 (customer advises not authorized) and R29 (corporate customer advises not authorized) carry potential NACHA violation risk if you retry; treat them as permanent stops
Return timeframes vary: most consumer returns are 2 banking days, but R07/R10 can come up to 60 calendar days after settlement, so do not close cases prematurely
Some processors deliver returns as separate ACH files rather than real-time webhooks; ensure your reconciliation window accounts for late-arriving return files
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp