Standardized Error Codes for Bank Import Plug-ins

What changed

NetSuite now defines a standardized set of error codes for all bank import processes — manual and automatic — across CSV, BAI2, and CAMT053 (ISO 20022) file formats. Previously, errors surfaced as free-text messages written by individual plug-in authors or as generic system messages, making programmatic handling and support triage difficult.

The new codes follow a fixed ten-character pattern: XYYYNNNNZZ

• X — Error scope: 0 = file/import-level, 1 = record-level (transaction, balance), 2 = account-level
• YYY — Data format: 000 = format-agnostic, 010 = CSV, 020 = BAI2, 030 = CAMT053
• NNNN — Specific numeric error identifier
• ZZ — Variant or subtype

For manual imports using the default BAI2 and CSV parsers, standardized codes are available automatically — no plug-in changes needed. For automatic imports, the codes only appear after the relevant plug-in has been updated.

If a plug-in still emits a free-text failure reason, a warning is displayed to users who hold the Financial Institution Records permission with Edit access. Oracle has stated that free-text failure reasons are targeted for removal in a future release.

Error code scope

The reference defines roughly 70 codes across four groups:

Import-level errors (0000xxxxxx)

• Connectivity failures (0000000001), data retrieval issues (0000000002), inactive plug-ins (0000000100–0000000102), transaction-limit exceeded (0000000200), timeout (0000300000), SFTP connection and file-matching errors (0000400000–0000400004), and retry scenarios (0000500000).

Account-level errors (2000xxxxxx)

• Locked accounts, expired or incorrect credentials, MFA prompts, consent revoked/expired, unsupported financial institution, and refresh timeouts.

Parser / record-level errors (1000xxxxxx)

• Invalid or incorrectly formatted dates and amounts, missing mandatory fields (amount, date, transaction type, account, currency, balance), invalid transaction types, unmapped account identifiers, field-length violations, record-count mismatches, control-total mismatches, and unclosed CSV quotes.

Format-specific structural errors

• CSV (0010xxxxxx): Invalid headers, wrong file format.
• BAI2 (0020xxxxxx): Out-of-order records, mismatched header/trailer pairs, missing mandatory header/trailer fields, invalid version, unrecognized record types, invalid group status IDs.
• CAMT053 (0030xxxxxx): Malformed XML, invalid group-header count or placement, missing creation datetime, missing statement, unmapped IBAN, missing account in statement.

What to do

1. If you maintain a Financial Institution Connectivity Plug-in:
   • Add the errorCode field to account-level error responses. See Oracle's Updating Connectivity Plug-ins for Account Error Codes documentation.
   • Add import-level standardized error handling. See Updating Connectivity Plug-ins for Import Error Codes.
2. If you maintain a Financial Institution Parser Plug-in:
   • Implement the addError API for parser-level errors. See Updating Parser Plug-ins for Parser Error Codes.
   • Add import-level standardized error handling. See Updating Parser Plug-ins for Import Error Codes.
3. Map each handled error scenario in your plug-in to the correct code from the reference table. Oracle expects every scenario your plug-in catches to return or set one of the listed codes.
4. Test in Sandbox. After updating, trigger each error path and verify the Banking Import History page displays the standardized code and message rather than free-text output.
5. Plan for deprecation. Free-text failure reasons will be removed in a future release. Any plug-in that has not adopted the errorCode / addError API by that time will produce degraded error reporting.

Caveats

The source page is a reference document, not a versioned release note — there is no explicit NetSuite release version attached. The exact release in which this error-code framework became available is not stated. Verify against your account's release version and the SuiteAnswers article history to determine when these APIs became available in your environment. The addError API and errorCode field surface area are not fully documented on this page; consult the linked plug-in update guides for method signatures and parameter details.