An exception is a business condition that stops ACH file processing or requires special handling. It differs from an error, which prevents processing because of a technical or structural problem, and from a warning, which notifies users without necessarily stopping processing. Exceptions can arise from malformed data or business rules such as unusually large transactions, flagged customers, or concerning activity. section 8.2
Treat exceptions as part of the normal product workflow rather than as rare failures. A payment file may be rejected at the file, batch, or entry level; the response can range from requesting a replacement file to recovering from a condition when appropriate. Correct routing-number validation also protects against processing a file intended for another institution, with customer-privacy and regulatory consequences. section 2.6 section 8.3.1
Common exception levels include:
- File-level exceptions: invalid header or trailer values, such as a lowercase file ID modifier, an unexpected immediate destination, changed blocking factor, or incorrect record size. section 8.3.1
- Entry-level exceptions: invalid account numbers or amounts, or insufficient funds for a transaction. section 8.3.3
- Cross-record and business-rule exceptions: trace numbers that do not ascend or a file whose company totals exceed configured limits. section 8.5 section 10.7.2
Build support in short cycles: first create a file that contains the desired condition, then update parsing and persistence, and finally expose the result in the dashboard. Field-level formatting rules can be expressed through Pydantic constraints and regular expressions; rules requiring relationships across records belong outside Pydantic. Use a failing test to define each expected exception, then add the processing logic and refactor repeated test setup. section 8.0 section 8.5 section 8.4 section 8.5.1
Testing an invalid destination
Create an ACH file with an invalid immediate destination, process it, retrieve stored exceptions, and assert that exactly one exception has the INVALID_IMMEDIATE_DESTINATION code. This verifies not merely that parsing failed, but that the application recorded the expected business condition for later display. section 8.5.1
Listing 8.8 Test for invalid immediate destination
def test_incorrect_immediate_destination(parser):
ach_filename = "invalid_immediate_destination.ach" #1
dir_path = os.path.dirname(os.path.realpath(__file__)) #2
file_path = os.path.join(dir_path, "data", "bad_files", #2
ach_filename) #2
expected_exceptions_count: int = 1
expected_exceptions_code: str = #2
AchExceptions.INVALID_IMMEDIATE_DESTINATION.value #3
ach_files_id =
SqlUtils.create_ach_file_record(filename, "123456789") #3
parser.parse(ach_files_id, file_path) #4
exceptions = SqlUtils.get_exceptions() #5
assert ( #6
len(exceptions) == expected_exceptions_count #6
), f"Expected {expected_exceptions_count}, #6
➥ but got {len(exceptions)}" #6
#6
assert ( #6
exceptions[0] == expected_exceptions_code #6
), f"Expected {expected_exceptions_code}, #6
➥ but got {exceptions[0]}" #6
Review the test structure that processes a bad ACH file and verifies its stored exception count and code. section 8.5.1
Make exceptions actionable in the interface. An exceptions page can list each exception, show its originating record, and link back to its file. As daily file volume grows, use pagination, search, and filtering to avoid overwhelming users or degrading dashboard performance. A DataGrid can supply sorting, searching, and filtering while an API retrieves exception details for a selected row. section 8.7.1
Graceful exception handling gives users feedback about improperly formatted uploads and an opportunity to recover. End-to-end support joins backend validation, database records, APIs, and responsive UI components so operational users can find and investigate exceptions. section 8.8.4
