Error codes: checks

Overview

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

Error response format

{
    "errors": [
        {
            "code": 2301,
            "message": "Deposits not allowed for account type"
        }
    ]
}

Error codes by category

Payment processing errors (2000-2034)

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

Code	Description	Resolution
2000	General exception	Review error details. Contact support if the 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 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 check return code
2015	Invalid dishonored return code	Dishonored return code is not valid. Provide a valid 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.
2031	Payment image data not available	Check image data is not available. Verify image upload was successful.
2032	Invalid front image format	Front check image format is invalid. Provide image in base64-encoded format.
2033	Invalid back image format	Back check image format is invalid. Provide image in base64-encoded format.
2034	Payment amount cannot be changed	Payment amount is locked and cannot be modified

Batch errors (2200-2202)

Errors related to check batch processing and authorization.

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 payments	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.

Configuration errors (2300-2331)

Errors related to account, product, and global configuration management.

Code	Description	Resolution
2300	No active configuration found for account	Account must have an active configuration. Create or activate account configuration.
2301	Deposits not allowed for account type	Account type does not support check deposits. Verify account configuration.
2306	Max payment amount exceeded	Payment amount exceeds maximum limit. Reduce amount or increase limit.
2309	Origination not allowed from a restricted account	Account has restrictions that prevent check origination
2310	Account config change not approved	Account configuration change must be approved before applying
2311	Account config change not pending	Operation requires account change to be in pending status
2312	Account config change approval requires dual control	Have a second authorized user approve the account configuration change
2313	Account configuration not found or is invalid	Verify account configuration ID is correct and configuration exists
2314	Global profile not found or is invalid	Verify global profile ID is correct and profile exists
2315	Global profile change not approved	Global configuration change must be approved before applying
2316	Global profile change not pending	Operation requires global profile change to be in pending status
2317	Product change not pending	Operation requires product change to be in pending status
2318	Product change not approved	Product configuration change must be approved before applying
2319	Global config change approval requires dual control	Have a second authorized user approve the global configuration change
2320	Global config required	Include global configuration object in the request
2321	Global config accounts must be unique	Use different account numbers for each global configuration field
2323	Inbound Suspense Account not found	Configure a valid inbound suspense account
2324	Outbound Suspense Account not found	Configure a valid outbound suspense account
2325	Return Account not found	Configure a valid return account
2326	Operator Account not found	Configure a valid operator account
2327	Unposted Account not found	Configure a valid unposted account
2328	Product config change approval requires dual control	Have a second authorized user approve the product configuration change
2329	Account config required	Include account configuration object in the request
2330	Product config required	Include product configuration object in the request
2331	Printing Account not found	Configure a valid printing account

Distribution errors (2400-2418)

Errors related to check distribution lifecycle management.

Code	Description	Resolution
2400	Distribution must be generating	Operation requires distribution to be in generating status
2401	Distribution already canceled	Distribution has already been canceled; cannot cancel again
2402	Distribution must be pending	Operation requires distribution to be in pending status
2403	Distribution must be on hold	Operation requires distribution to be in hold status
2404	Distribution must be verified	Operation requires distribution to be in verified status
2405	Distribution must be released	Operation requires distribution to be in released status
2406	Distribution must not be released	Operation requires distribution to not be released yet
2407	Distribution must be transmitted	Operation requires distribution to be in transmitted status
2408	Distribution must be acknowledged	Operation requires distribution to be in acknowledged status
2409	Distribution must be processing	Operation requires distribution to be in processing status
2410	Distribution must have been previously transmitted	Distribution must have been transmitted at least once
2411	Distribution release requires dual control	Have a second authorized user approve the distribution release
2412	A distribution is currently generating	Another distribution is currently generating. Wait for completion.
2413	No payments to distribute	Distribution must contain at least one payment
2414	Distribution is currently processing and can no longer be acknowledged	Distribution is processing. Acknowledgment window has closed.
2415	Distribution is currently complete and can no longer be acknowledged	Distribution is complete. Acknowledgment is no longer available.
2416	Cannot verify distribution with exceeded limits	Distribution exceeds configured limits. Review and adjust limits or distribution.
2417	No filters were found on the request	Include filter parameters in the request. Specify search criteria.
2418	Only one distribution per minute is allowed	Wait at least one minute before creating another distribution

Submission errors (2500-2501)

Errors related to check submission processing.

Code	Description	Resolution
2500	Submission import count cannot exceed total payment count	Import count is invalid. Ensure it does not exceed total payment count.
2501	Submission process count cannot exceed total payment count	Process count is invalid. Ensure it does not exceed total payment count.

Hold errors (2600-2603)

Errors related to check payment hold management.

Code	Description	Resolution
2600	Hold is not active	Hold must be in active status for this operation. Verify hold status.
2601	Hold payment not found	Verify hold payment ID is correct. Check if hold payment exists.
2602	No filters were found on the request	Include filter parameters in the request. Specify search criteria.
2603	This action requires dual control	Have a second authorized user approve the hold operation

Security errors (3000-3002)

Security-related errors including permissions and access control.

Code	Description	Resolution
3000	General exception	Review error details. Contact support if the issue persists.
3001	Flags not allowed	User does not have permission to set flags. Contact administrator.
3002	Clearing hold exceeds user permissions for payment amount	Payment amount exceeds user's hold clearance dollar limit. Request approval from higher authority.

Configuration access errors (3200)

Configuration-specific access control errors.

Code	Description	Resolution
3200	Access denied	User lacks permission to access configuration. Verify user has appropriate role and permissions.