Error codes: ACH

Overview

This page provides comprehensive error code information for the ACH API, including error codes, descriptions, and resolution guidance based on actual codebase analysis.

Error response format

{
    "errors": [
        {
            "code": 1000,
            "message": "Receiver.RoutingNumber is missing or invalid"
        }
    ]
}

Error codes by category

Validation errors (1000-1001)

General validation errors for ACH operations.

Error Code	Description	Resolution
1000	General exception	General validation error; check request parameters and contact support if issue persists
1001	Payment required	Payment object is required in the request; include payment details

Payment processing errors (2000-2030)

Errors related to ACH payment processing, status management, and validation.

Error Code	Description	Resolution
2000	General exception	General application error; check request parameters and contact support if issue persists
2001	Invalid payment status	Check current payment status; verify the requested operation is valid for the current status
2002	Invalid posting status	Payment posting status does not allow the requested operation; verify posting status
2003	Payment cannot be canceled	Payment status does not allow cancellation; verify payment is in cancellable status
2004	Account not found	Verify the account number is correct; check if account exists in the system
2005	Payment must be outbound	Operation requires payment to be outbound; verify payment direction
2006	Payment must be inbound	Operation requires payment to be inbound; verify payment direction
2007	Payment must be an inbound origination	Operation requires an inbound origination payment type
2008	Payment must be status completed or rejected to be corrected	Payment correction requires completed or rejected status; verify payment status
2009	Invalid change code	Change code is not valid; provide a valid NACHA change code
2010	Payment must be an inbound return	Operation requires an inbound return payment type
2011	Payment must be an origination	Operation requires an origination payment type
2012	Payment must be status completed or rejected to be returned	Payment return requires completed or rejected status; verify payment status
2013	Payment must be status completed or rejected to be dishonored	Payment dishonor requires completed or rejected status; verify payment status
2014	Invalid return code	Return code is not valid; provide a valid NACHA return code
2015	Invalid dishonored return code	Dishonored return code is not valid; provide a valid NACHA dishonored return code
2016	Original payment not found	Verify original payment ID is correct; check if original payment exists
2017	Cannot link to same payment ID	Linked payment ID must be different from current payment ID
2018	Payment type must be return or notification of change	Operation requires payment to be a return or NOC type
2019	Original payment must be completed	Linked original payment must be in completed status
2020	Payment must be on hold to request a rescan	Payment must be in hold status before requesting a rescan
2021	No scan lists are configured for account	Configure scan lists for the account before requesting scans
2022	Scan already pending	A scan is already in progress; wait for current scan to complete
2023	Previous payment not found	Verify previous payment ID is correct; check if previous payment exists
2024	Previous payment must be a completed outbound origination	Previous payment must be an outbound origination in completed status
2025	Receiver account not found	Verify receiver account number is correct; check if account exists
2026	Active holds found	Payment has active holds; resolve or release holds before processing
2027	Posting account cannot be changed due to current payment status	Payment status does not allow posting account changes
2028	Posting status must be pending or failed to change posting account	Posting account can only be changed when posting is pending or failed
2029	Posting status must be failed to attempt a retry	Only failed postings can be retried; verify posting status
2030	Originator profile address missing or invalid	Provide complete originator address information; verify address format

Batch errors (2200-2202)

Errors related to ACH batch processing and authorization.

Error Code	Description	Resolution
2200	Batch not authorizing	Batch must be in authorizing status for this operation; verify batch status
2201	Batch requires one or more payment	Batch must contain at least one payment; add payments to batch
2202	No filters were found on the request	Include filter parameters in the request; specify search criteria