File Submission Validation Errors

Introduction

When submitting files to Lead, the system validates records across multiple layers — from field formatting to cross-file reconciliation — to ensure data integrity for regulatory reporting and moving funds between accounts. This page breaks down error types and messages so you can quickly identify, troubleshoot, and resolve issues.

Overview of File Validation Errors

The system performs validation in sequential groups. If a file fails in an earlier group, the system does not execute validations in later groups — so the absence of errors in a later group does not mean the file passed those validations. For example, if the balances file fails a validation in group two, group three validations do not run.

1. File Integrity

Category	Description	Scope	Examples
File Integrity	Checks ensuring that the file is formatted correctly and fields/records are unique	Within a specific file	Balance IDs must be unique; entire records cannot be duplicated

2. Record Evaluation in the Same File

The system evaluates the three categories (Field Format, Business Rules, and Program Configuration) at the same time. The table below lists them separately as these are conceptually different types of validation checks.

Category	Description	Scope	Examples
Field Format	Single-field checks ensuring a value is well-formed before any business logic is applied	Single field within a record in a specific file	`card_transaction_effective_at` must be an ISO 8601 date; `amount_in_usd` must have a minimum of 2 decimal places; `account_holder_type` is either `consumer` or `commercial`
Business Rules	Rules evaluating the meaning or combination of fields within a single record	Multiple fields within a record in a specific file	`authorized_signers` is required if `account_holder_type` = `commercial` and must be a list of size >= 1; `balance` = `outstanding_principal` + `outstanding_interest` + `outstanding_fees`
Program Configuration	Rules verifying that records align with your program’s configuration based on your product offerings	One record in a specific file against your program setup (Reach out to your dedicated Technical Account Manager (TAM) to understand if these apply to you)	`client_settlement_bank_account_id` must be an eligible enum

3. Record Evaluation Across Files

Category	Description	Scope	Examples
Cross-File Reconciliation	Checks spanning multiple files across days and objects to ensure accurate data over time	Multiple files — can be the same or different objects for the same or different file dates	Balance on T = Balance on T-1 + Transaction activity on T; every non-closed account from T-1 must be reported in the balances file on T

File Integrity

File Integrity checks run first and validate the structure and uniqueness of the file itself, before any field-level or business logic evaluation begins. The system applies the following checks:

Duplicate Detection: Identifies records where every field value in one record is identical to every field value in another record in the same file.
Duplicate Primary Keys: Validates that each record’s primary key only appears once in the file. For example, in the Accounts schema, the primary key is client_account_id.
Non-empty Files: Validates that required files are not empty (e.g., network settlement files must have at least one record).
Single Settlement Date: All records in a network settlement file must share the identical settlement date.

Error Codes

Error Code	Description	How to Resolve
`balance_already_exists_for_date`	A balance record for this account already exists for this file date. Each account may only have one balance record per file date.	Remove the duplicate balance record.
`csv_file_parse_failure`	The file could not be parsed as a valid CSV. This may be caused by malformed records, unescaped quotes, or incorrect delimiters.	Inspect the file for formatting issues such as unescaped pipe characters, unclosed quotes, or non-standard line endings. Ensure the file uses pipe (\|) delimited formatting.
`empty_csv_files_with_no_headers`	The CSV file is empty or is missing a header record.	Add a valid header followed by at least one record.
`empty_network_settlement_file`	The network settlement file contains no records. At least one record is required.	Add at least one valid settlement record.
`invalid_metadata_json`	The metadata JSON in the file is malformed and cannot be parsed.	Verify the metadata JSON uses valid JSON syntax and conforms to the expected structure.
`schema_mismatch`	The file columns or structure do not match the expected schema. A required column may be missing, misspelled, or in the wrong order.	Compare the file headers against the required schema for this file type. Ensure all required columns are present and correctly named.
`settlement_date_error`	The settlement date in the file is invalid or does not match the expected value.	Verify the settlement date matches the file date and is correctly formatted as `YYYY-MM-DD`.
`settlement_date_mismatch`	The `settlement_date` value in one or more records does not match the date in the filename. All records in a network settlement file must share the same settlement date, which must equal the file date.	Update all `settlement_date` values to match the date in the filename.

Field Format

Field Format checks validate individual field values in isolation — confirming that each value is correctly entered, properly formatted, and within its allowed constraints before any business logic runs. The system applies the following checks:

Data Type Checks: Validates that the value meets the criteria for that specific data type (e.g. decimal fields should be a decimal, not a string).
Format Checks: Based on the field, additional validation checks for the semantic meaning of that value, such as ISO 8601 date/datetime formats, US ZIP codes, US state codes, ISO 3166 country codes, and ISO 4217 currency codes.
Data Constraints: Enforces required field presence, allowed value sets (enums), and maximum string lengths.
Decimal Place Requirements: Enforces that a decimal has a specific number of decimal places. Most commonly found with fields that represent currencies (e.g. if the balance is in USD, it has two decimal places). Some common variations are:
- Interest/APR rate precision strictly enforced to 3 or 6 decimal places.
- amount_in_usd must always have exactly 2 decimal places.
- Minimum or maximum decimal bounds, including special-case decimals for accrued interest.

Error Codes

Field format errors are field-specific and follow predictable patterns tied to each file’s schema. This document does not enumerate individual error codes here because they map directly to schema-level field definitions — the error code itself (e.g., balance_currency_missing, transaction_effective_at_invalid_format) identifies both the file and the field in question. To understand whether a field is required, along with its format, allowed values, and precision, refer to the schema reference for the file type you are validating.

Business Rules

Business Rules evaluate the meaning and relationships between fields within a single record — going beyond format to ensure the data is internally consistent and logically valid. The system applies the following checks:

Polarity: Validates that the sign of the amount field in the Transactions File is consistent with the transaction type, transfer type, and applied field.
Component Constraints: Enforces non-zero amounts only on applicable types for principal, interest, and fee fields.
Relational Rules:
- Balance Composition: Enforce that a top-level amount is fully and correctly broken down into its components. Amount = Principal + Interest + Fee
- Status Pairing: Ensures valid status to status_reason pairings (e.g., in the Accounts schema, a “closed” status must pair with entity_closed, client_closed, etc.).
- Past Due Consistency: All four past-due fields must be completely present or completely absent.
- Balance Constraints: Dispute or charge-off balances must be ≤ the main balance.
- Repayment Details: Type and frequency are strictly required when the program structure demands it.
- Commercial Accounts: authorized_signers are required when account_holder_type = commercial
Timestamp Ordering: Timestamps must follow a logical ordering sequence. For example, a record cannot be updated before it is created

Error Codes

Accounts

Error Code	Description	How to Resolve
`commercial_account_must_have_authorized_signers`	A commercial account (`account_holder_type` = `commercial`) must have at least one authorized signer. Learn More	Add a valid list of authorized signers to the commercial account record.
`currency_update_not_allowed`	The `currency` field cannot be changed after the record is created. Learn More	Remove the currency update from the record. If the currency was set incorrectly at creation, contact your Technical Account Manager to correct it.

Balances

Error Code	Description	How to Resolve
`balance_cannot_be_closed_with_non_zero_balance`	A balance cannot be moved to `closed` status while it still has a non-zero `balance`. Learn More	Zero out the balance before marking it closed, or update `status` to reflect the balance’s actual state.
`balance_client_balance_id_not_allowed_for_funding`	`client_balance_id` is not permitted for funding programs. Funding programs must use `id` instead. Learn More	Remove `client_balance_id` from the record and use the `id` field for funding program balances.
`balance_currency_must_be_usd_for_funding`	The `currency` value must be `USD` for funding programs. Other currencies are not supported. Learn More	Update `currency` to `USD` for all funding program balance records.
`balance_invalid_effective_date`	The `effective_at` value on the balance could not be parsed or is not one day prior to the file date. Learn More	Ensure `effective_at` is a valid ISO 8601 datetime set to the day before the file date.
`balance_max_funding_amount_invalid_for_revolving`	`max_funding_amount` must not be populated when `structure` is `revolving`. Learn More	Remove `max_funding_amount` from revolving balance records.
`balance_past_due_balance_invalid_days`	When `past_due_balance` is greater than 0, at least one of `past_due_principal`, `past_due_interest`, or `past_due_fees` must also be greater than 0, and `past_due_days` must be greater than 0. Learn More	If `past_due_balance` is non-zero, ensure at least one of the breakdown fields and `past_due_days` are also non-zero.
`balance_receivable_transferred_invalid_status_reason`	When `status` is `receivable_transferred`, `status_reason` must be set to `receivable_sold_to_partner`. No other `status_reason` is valid for this status. Learn More	Set `status_reason` to `receivable_sold_to_partner` when `status` is `receivable_transferred`.
`balance_receivable_transferred_only_for_credit`	The `receivable_transferred` status is only valid for balances with `type` = `credit`. Learn More	Change the `status` of the balance record to an eligible enum.
`balance_term_unit_invalid_for_revolving`	`term_unit` must not be populated when `structure` is `revolving`. Learn More	Remove `term_unit` from revolving balance records.
`balance_term_value_invalid_for_revolving`	`term_value` must not be populated when `structure` is `revolving`. Learn More	Remove `term_value` from revolving balance records.
`balance_type_funding_program_must_be_credit`	The `type` value must be `credit` for funding programs. Other balance types are not supported. Learn More	Update `type` to `credit` for all funding program balance records.
`invalid_balance`	The `balance` value does not match its component fields. For credit balances, `balance` must equal `outstanding_principal` + `outstanding_interest` + `outstanding_fees`. Learn More	Recalculate `balance` to equal the sum of its components.
`invalid_past_due_balance`	The `past_due_balance` exceeds `balance`, or `past_due_balance` must be zero when `balance` is negative. Learn More	Ensure `past_due_balance` is less than or equal to `balance` and is zero when `balance` is negative.
`invalid_past_due_fee`	The `past_due_fees` exceeds `outstanding_fees`, or `past_due_fees` must be zero when `balance` is negative. Learn More	Ensure `past_due_fees` does not exceed `outstanding_fees` and is zero when `balance` is negative.
`invalid_past_due_interest`	The `past_due_interest` exceeds `outstanding_interest`, or `past_due_interest` must be zero when `balance` is negative. Learn More	Ensure `past_due_interest` does not exceed `outstanding_interest` and is zero when `balance` is negative.
`invalid_past_due_principal`	The `past_due_principal` exceeds `outstanding_principal`, or `past_due_principal` must be zero when `balance` is negative. Learn More	Ensure `past_due_principal` does not exceed `outstanding_principal` and is zero when `balance` is negative.
`unexpected_balance`	The `balance` does not equal the sum of `outstanding_principal` + `outstanding_interest` + `outstanding_fees`. Learn More	Recalculate `balance` to equal the sum of its component fields.
`unexpected_past_due_balance`	The `past_due_balance` does not equal the sum of `past_due_principal` + `past_due_interest` + `past_due_fees`. Learn More	Recalculate `past_due_balance` to equal the sum of its component fields.

Transactions

Error Code	Description	How to Resolve
`amount_and_settlement_amount_are_not_same_signage`	The `amount` and `settlement_amount` fields have different signs. Both must be positive or both must be negative. Learn More	Update `amount` and `settlement_amount` to have matching signs.
`incorrect_currency_rate`	The `amount` and `amount_in_usd` values on the transaction do not match for a USD-denominated transaction. Learn More	Verify that `amount` and `amount_in_usd` are consistent. For USD transactions, both values should be equal.
`transaction_amount_wrong_polarity`	The `amount` value has the wrong sign for the specified `action`. Debit actions require a negative amount; credit actions require a positive amount. Learn More	Update `amount` to match the expected sign for the `action` field.
`transaction_card_authorization_amount_invalid_value`	`card_authorization_amount` is present but must be empty when `transfer_type` is not `card`. Learn More	Remove `card_authorization_amount` from records where `transfer_type` is not `card`, or correct `transfer_type`.
`transaction_invalid_amount`	The transaction `amount` does not equal the sum of `principal_amount`, `interest_amount`, and `fee_amount` for a credit balance transaction. Learn More	Recalculate `amount` to equal the sum of its component fields (`principal_amount` + `interest_amount` + `fee_amount`).
`transaction_invalid_effective_date`	The `effective_at` value on the transaction is invalid or is not exactly one day prior to the file date. Learn More	Ensure `effective_at` is a valid ISO 8601 datetime set to the day before the file date. For example, if the file date is `2025-12-31`, `effective_at` must be an ISO 8601 datetime starting with `2025-12-30`.
`transaction_invalid_settlement_date`	The `settlement_date` on the transaction is invalid for the given `type` and `transfer_type`. The expected value varies: • Zero-day hold programs (`transfer_type` = `card`, `aft`, or `oct`): file date (T) • `type = fee`: T-1 • Card refunds with T-3 settlement enabled: between T-3 and T (inclusive) • `transfer_type = card` with `network_code = PULSE`: any value accepted • Most card and AFT/OCT transactions: ≥ T-1 • `type = disbursement` with `transfer_type = internal_transfer` and a `funding_id`: T-1 Learn More	Verify `settlement_date` is a valid ISO 8601 date that matches the expected value for this transaction’s `type` and `transfer_type`.
`transaction_invalid_type_and_action_combinations`	The combination of `type` and `action` is invalid. Not all transaction types are compatible with all action values. Learn More	Review the allowed type-and-action combinations for your program type and correct the record.
`transaction_on_non_active_balance`	The transaction references a balance that does not have `active` status. Transactions can only be applied to active balances. Learn More	Verify the `balance_id` references an `active` balance. If the balance is inactive or closed, correct the `balance_id` or update the balance status.
`transaction_rewards_amount_invalid_value`	The `rewards_amount` value is invalid. Either the amount should be zero, or the transaction `type` does not support a non-zero rewards amount. Learn More	Set `rewards_amount` to `0.00` if no rewards apply, or update `type` to one that accepts rewards.
`transaction_rewards_amount_wrong_polarity`	The `rewards_amount` value has the wrong sign for the specified `action`. Debit actions require negative amounts; credit actions require positive amounts. Learn More	Update `rewards_amount` to match the expected sign for the `action` field.
`transaction_type_invalid_activity_check`	The `principal_amount`, `interest_amount`, and `fee_amount` values are inconsistent with the transaction `type`. Certain types require specific amount combinations. Learn More	Verify that the amount breakdown matches the expected pattern for this transaction `type`.
`transaction_zero_value`	The transaction `amount` is zero. Zero-value transactions are not allowed. Learn More	Set `amount` to a non-zero value or remove the transaction record.
`transactions_funding_id_invalid_transaction`	`funding_id` is populated on a transaction that does not have `type` of `disbursement` and `transfer_type` of `internal_transfer`. This field is not valid for this combination. Learn More	Remove `funding_id` from transactions where `type` is not `disbursement` or `transfer_type` is not `internal_transfer`.
`transactions_funding_id_invalid_value`	The `funding_id` value is invalid. It must be present when `type` is `disbursement` and `transfer_type` is `internal_transfer`, and must be empty otherwise. Learn More	Verify `funding_id` is set correctly for the transaction type and transfer type combination.

Collaterals

Error Code	Description	How to Resolve
`collateral_address_city_not_allowed`	`address_city` must be empty when `type` is not `real_estate`. Learn More	Remove `address_city` from non-real_estate collateral records.
`collateral_address_country_not_allowed`	`address_country` must be empty when `type` is not `real_estate`. Learn More	Remove `address_country` from non-real_estate collateral records.
`collateral_address_line_1_not_allowed`	`address_line_1` must be empty when `type` is not `real_estate`. Learn More	Remove `address_line_1` from non-real_estate collateral records.
`collateral_address_line_2_not_allowed`	`address_line_2` must be empty when `type` is not `real_estate`. Learn More	Remove `address_line_2` from non-real_estate collateral records.
`collateral_address_postal_code_not_allowed`	`address_postal_code` must be empty when `type` is not `real_estate`. Learn More	Remove `address_postal_code` from non-real_estate collateral records.
`collateral_address_state_not_allowed`	`address_state` must be empty when `type` is not `real_estate`. Learn More	Remove `address_state` from non-real_estate collateral records.
`collateral_effective_at_not_t_minus_one`	The `effective_at` value must be exactly T-1 — one calendar day before the file date. Learn More	Update `effective_at` to the day immediately preceding the file date.
`collateral_value_in_usd_not_allowed`	`value_usd` must be empty when `balance_id` is present. Only one of these fields may be populated per record. Learn More	Remove `value_usd` from records where `balance_id` is provided.

Program Configuration

Program Configuration checks verify that submitted records are consistent with your program’s specific setup — such as eligible transaction types, supported currencies, and required bank account identifiers. These rules vary by program, so not all of the following checks may apply to you. The following checks are applied:

Allowed Transactions: Validates allowed transaction types, transfer types, and fee types per your specific program (credit, deposit, or funding).
Settlement Accounts: client_settlement_bank_account_id must match one of the bank accounts established in the program’s configuration.
Funding Constraints: Funding programs must use the Credit balance type, USD currency, and omit the client_balance_id.
Multi-Currency Exceptions: Multi-currency programs have relaxed settlement currency matching, but amount_in_usd is required.
- Settlement Currency: Must equal the transaction currency, unless the program is configured to support multiple currencies.
Conditional Fields: Certain fields are conditionally required depending on if your program is a non-funding type. funding_id requirements depend on the transaction type and your program configuration.

How to Resolve

Because these validations depend on your specific program configuration managed by Lead, you cannot resolve them independently.

Contact your Technical Account Manager to confirm which validations apply to your program.

Cross-File Reconciliation

Cross-File Reconciliation checks run last and compare data across multiple files or against prior successful submissions — ensuring consistency over time and across related records. These checks only run after the file passes all earlier validation categories. The following checks are applied:

Continuity: Balances that are not in a closed status from yesterday’s file must appear in today’s file.
Existence: All foreign keys correctly reference an existing object. For example, in the Transactions file, the balance_id and card_id must be existing Objects.
Daily Balance Checks: Ensures that today’s balance (T) equals yesterday’s balance (T-1) plus today’s daily activity. This is verified for the overall balance, and independently for principal, interest, fees, dispute, charge-off, and rewards components.
Card Network Settlement Matching: The sum of transaction amounts per network must equal network_settlement.TransactionAmount. This applies to refunds as well.
Duplicate Protection: Prevents the reuse of transaction IDs across files.

Error Codes

Applications

Error Code	Description	How to Resolve
`application_exists_in_terminal_status`	A record for this `client_application_id` has already been processed and is in a terminal status (`approved`, `declined`, or `canceled`). Applications in a terminal status cannot be resubmitted or updated. Learn More	Remove the duplicate application record. If this is a new application, assign a unique `client_application_id`.
`entity_does_not_exist`	An entity referenced on this application (`account_holders`, `authorized_signers`, or `authorized_users`) could not be found in the system. Entities must be created before they can be referenced on an application. Learn More	Verify the entity identifier is correct and that the entity has been successfully created before referencing it on this application.
`entity_does_not_have_correct_role`	An entity referenced as an account holder or authorized signer on an approved application does not have the required role. The entity exists in the system but has not been assigned the role needed for this position on the application. Learn More	Ensure the entity has been assigned the correct account holder or authorized signer role before referencing it on an approved application.

Accounts

Error Code	Description	How to Resolve
`account_already_exists`	An account with this identifier has already been created. Duplicate account submissions are not allowed. Learn More	Remove the duplicate account record. If this is a distinct new account, assign a unique identifier.
`account_application_already_used`	The referenced application has already been used to create an account. Each application can only be used once. Learn More	Use a different application for this account, or verify the existing account record is correct and remove the duplicate.
`account_application_does_not_exist`	The referenced application does not exist. The account cannot be created because the application could not be found. Learn More	Verify the application identifier is correct and that the application was successfully submitted and approved before creating the account.
`account_application_not_approved`	The referenced application has not been approved. Account creation requires an approved application. Learn More	Ensure the application is in an approved state before submitting an account record that references it.
`account_field_cannot_be_updated`	One or more immutable fields in the account record have changed from a prior submission. These fields cannot be updated after the account is created. Learn More	Restore the immutable field values to match prior submissions. If the field value must be corrected due to an error, contact your Technical Account Manager.
`account_fields_do_not_match_application_fields`	Fields in the account record do not match the corresponding fields in the referenced application. Account details must be consistent with the application. Learn More	Update the account fields (such as entity, name, and address details) to match the application.
`account_id_already_exists_for_approved_application`	An account ID already exists for the referenced approved application. Each application can only create one account. Learn More	Verify whether an account already exists for this application before attempting to create another. Remove the duplicate.
`account_with_update_not_approved`	The account is already in a terminal status and cannot be updated. Once an account reaches a terminal status, further updates to the record are not permitted. Learn More	Remove the update for this account. If the terminal status was applied in error, contact your Technical Account Manager.
`application_exists_in_terminal_status`	The referenced application is in a terminal status (e.g., declined or canceled) and cannot be used to create an account. Learn More	Submit a new application before creating the account, or reference a non-terminal application.
`effective_at_not_greater_than_previous_effective_at`	The `effective_at` value in this account record is not later than the `effective_at` from the prior submission for this account. Records must be submitted in chronological order. Learn More	Ensure the `effective_at` is later than the previous record’s `effective_at` for this account.
`entity_does_not_exist`	An entity referenced on this account (`account_holders`, `authorized_signers`, or `authorized_users`) could not be found in the system. Entities must exist before they can be associated with an account. Learn More	Verify the entity identifier is correct and that the entity was successfully created before submitting this account record.
`entity_does_not_have_correct_role`	An entity referenced on this account does not have the required role for their listed position. Account holders must have the account holder role, authorized signers must have the authorized signer role, and authorized users must have the authorized user role. Learn More	Ensure each entity has been assigned the correct role before referencing them on an account.
`entity_does_not_have_credit_score`	The entity associated with this account does not have a credit score on record. A credit score is required for this account type. Learn More	Ensure a credit score has been submitted for this entity before creating the account.
`unexpected_authorized_user_in_account_file`	Authorized users must be submitted via the dedicated Authorized Users file, not within the Accounts file. One or more `authorized_users` entries were found in this record for a program configured to use the standalone Authorized Users file. Learn More	Remove `authorized_users` from the Accounts file and submit them via the Authorized Users file instead.

Authorized Users

Error Code	Description	How to Resolve
`authorized_user_update_stale`	The authorized user update is based on stale data. A more recent update for this authorized user already exists. Learn More	Retrieve the latest state of the authorized user record and re-submit the update based on current data.
`authorized_user_without_active_account`	An authorized user is associated with an account that does not have active status. Learn More	Ensure the account is active before associating authorized users, or remove the authorized user record.
`entity_does_not_exist`	The `entity_id` on this authorized user record could not be found in the system. The entity must be created before it can be added as an authorized user. Learn More	Verify the `entity_id` is correct and that the entity has been successfully created before submitting this authorized user record.
`entity_does_not_have_correct_role`	The entity referenced in this record does not have the authorized user role assigned. Only entities with the authorized user role can be added as authorized users. Learn More	Ensure the entity has been assigned the authorized user role before referencing it in the Authorized Users file.
`no_account_found_for_account_id`	No account exists for the given `account_id`. The referenced account has not been created or is not associated with this program. Learn More	Verify the `account_id` is correct and corresponds to an existing account. Ensure the Accounts file was successfully processed before referencing it in this file.
`no_authorized_user_role_found_for_entity_id`	No authorized user role was found for the given entity ID. The entity must have a valid authorized user role to be associated with an account. Learn More	Verify the entity ID is correct and that the entity has been created with the appropriate authorized user role.
`unexpected_authorized_user_in_account_file`	An authorized user record appears in the account file for an account that does not list them. Learn More	Remove the unexpected authorized user record or verify the account correctly reflects all intended authorized users.

Cards

Error Code	Description	How to Resolve
`account_does_not_exist`	The referenced account does not exist in the system. Learn More	Verify the account identifier is correct and that the account was previously submitted and processed.
`card_status_not_terminal_on_terminal_account`	The card must be updated to a terminal status because its associated account is in a terminal status. All cards must reach a terminal status when their account does. Learn More	Update the card to `closed` or `expired` before or alongside moving the account to a terminal status.
`card_with_update_not_approved`	The card cannot be updated because it is already in a terminal status. Exception: cards with a `closed` status may transition to `active` or `inactive`. Learn More	Remove the update or verify the transition from the card’s current terminal status is permitted.
`customer_not_authorized_on_account`	The card’s `entity_id` is not an account holder or authorized user on the linked account. For active cards, the authorized user must also be active; for inactive cards, active or inactive authorized user status is accepted. Learn More	Verify the card’s `entity_id` is listed as an account holder or authorized user on the associated account.
`replacement_card_not_found`	The card referenced in `replaced_by` could not be found. Fires when `replaced_by` is populated but the referenced card does not exist in the current file or in the system. Learn More	Verify the `replaced_by` card identifier is correct and that the referenced card exists in today’s file or has been previously submitted.

Balances

Error Code Renames — Effective August 4, 2026Several balance-related error codes are being renamed effective August 4, 2026. See the Changelog for the full list of changes and what action to take.

Error Code	Description	How to Resolve
`account_id_mismatch`	The `account_id` in today’s submission does not match the value from prior submissions for this balance. Learn More	Ensure `account_id` is consistent with prior submissions for this balance.
`balance_cannot_be_terminal_with_processing_funding`	This balance cannot be set to `closed` or `receivable_transferred` because it has associated funding requests in a processing state. Learn More	Wait until all in-flight funding requests have reached a terminal status before transitioning this balance to `closed` or `receivable_transferred`, then resubmit.
`balance_created_after_file_date`	The balance was created after the file date. Balances cannot be included in files dated before their creation date. Learn More	Remove the balance record from this file and submit it starting from the file date on or after the balance’s creation date.
`balance_not_recognized`	The balance record cannot be matched to any known balance in the system. Learn More	Verify the balance identifier is correct. If this is a new balance, ensure it was properly created before reporting it.
`balance_receivable_transferred_outstanding_receivables`	The balance cannot be set to `receivable_transferred` because it has outstanding receivables still held by Lead. All associated receivables must be sold from Lead to you before its status can be set to `receivable_transferred`. Learn More	Remove the `receivable_transferred` status change from the file and resubmit.
`client_settlement_bank_account_id_mismatch`	The `client_settlement_bank_account_id` does not match the value from a prior submission for this balance. Learn More	Ensure `client_settlement_bank_account_id` is consistent with prior submissions for this balance.
`created_at_timestamp_mismatch`	The `created_at` timestamp in today’s submission does not match the value recorded from the initial submission for this balance. This field is immutable after creation. Learn More	Restore the original `created_at` value from the initial balance submission.
`currency_mismatch`	The `currency` value does not match the value recorded from the initial submission for this balance. Currency is immutable after creation. Learn More	Restore the original `currency` value for this balance. If the currency was set incorrectly at creation, contact your Technical Account Manager to correct it.
`currency_update_not_allowed`	The `currency` value for this balance has changed from a prior submission. Currency is immutable after a balance is created. Learn More	Restore the original `currency` value. If the currency was set incorrectly at creation, contact your Technical Account Manager to correct it.
`effective_apr_mismatch`	The `effective_apr` value does not match the value from a prior submission for this balance. Learn More	Ensure `effective_apr` is consistent with prior submissions for this balance.
`effective_at_not_greater_than_previous_effective_at`	The `effective_at` value is not later than the previous record’s `effective_at`. Records must be submitted in chronological order. Learn More	Ensure each record’s `effective_at` is later than the preceding record’s `effective_at`.
`expected_finance_charge_amount_mismatch`	The `expected_finance_charge_amount` value does not match the value from a prior submission for this balance. Learn More	Ensure `expected_finance_charge_amount` is consistent with prior submissions.
`invalid_balance`	The `balance` does not match the sum of the prior day’s `balance` and the current day’s net transaction activity. Learn More	Recalculate `balance` to equal the prior day’s `balance` plus the sum of all transaction amounts for this reporting period.
`invalid_outstanding_fee`	The `outstanding_fees` reported does not match the expected value. It must equal the previous reporting day’s `outstanding_fees` plus the current reporting day’s fee activity. Learn More	Recalculate `outstanding_fees` to equal the prior day’s value plus net fee transaction activity.
`invalid_outstanding_interest`	The `outstanding_interest` reported does not match the expected value. It must equal the previous reporting day’s `outstanding_interest` plus the current reporting day’s interest activity. Learn More	Recalculate `outstanding_interest` to equal the prior day’s value plus net interest transaction activity.
`invalid_outstanding_principal`	The `outstanding_principal` reported does not match the expected value. It must equal the previous reporting day’s `outstanding_principal` plus the current reporting day’s principal activity. Learn More	Recalculate `outstanding_principal` to equal the prior day’s value plus net principal transaction activity.
`is_interest_based_mismatch`	The `is_interest_based` value does not match the value from a prior submission for this balance. Learn More	Ensure `is_interest_based` is consistent with prior submissions.
`max_funding_amount_mismatch`	The `max_funding_amount` value does not match the value from a prior submission for this balance. Learn More	Ensure `max_funding_amount` is consistent with prior submissions.
`previous_active_account_balance_missing`	A non-terminal account balance from the prior day is missing from today’s submission. All non-terminal balances must be reported every day. Learn More	Add the missing balance record to today’s file. If the balance is no longer active, report it with a terminal status.
`previous_active_balance_missing`	A balance that was active in the prior day’s submission is missing from today’s Balances file. Non-closed balances must be reported every day. Learn More	Add the missing balance record to today’s Balances file. All non-closed balances from the prior day must be included.
`previous_active_card_balance_missing`	A non-terminal card balance from the prior day is missing from today’s submission. All non-terminal card balances must be reported every day. Learn More	Add the missing card balance record to today’s file. If the balance is no longer active, report it with a terminal status.
`rewards_unit_mismatch`	The `rewards_unit` value does not match the value from a prior submission for this balance. Learn More	Ensure `rewards_unit` is consistent with prior submissions for this balance.
`structure_mismatch`	The `structure` field value does not match the value from a prior submission for this balance. Learn More	Ensure `structure` is consistent with all prior submissions for this balance. If a correction is needed, contact your Technical Account Manager.
`unexpected_charge_off_balance`	The `charge_off_balance` does not match the sum of its components (`charge_off_principal` + `charge_off_interest` + `charge_off_fees`), or does not reconcile with the prior day’s `charge_off_balance` plus current charge-off transaction activity. Learn More	Verify `charge_off_balance` equals the sum of its component fields and reconciles with the prior day’s value plus today’s charge-off transactions.
`unexpected_charge_off_fee`	The `charge_off_fees` does not reconcile with the prior day’s `charge_off_fees` plus current charge-off transaction activity affecting fees. Learn More	Verify `charge_off_fees` equals the prior day’s value plus net charge-off activity for fees.
`unexpected_charge_off_interest`	The `charge_off_interest` does not reconcile with the prior day’s `charge_off_interest` plus current charge-off transaction activity affecting interest. Learn More	Verify `charge_off_interest` equals the prior day’s value plus net charge-off activity for interest.
`unexpected_charge_off_principal`	The `charge_off_principal` does not reconcile with the prior day’s `charge_off_principal` plus current charge-off transaction activity affecting principal. Learn More	Verify `charge_off_principal` equals the prior day’s value plus net charge-off activity for principal.
`unexpected_dispute_balance`	The `dispute_balance` does not match the sum of its components (`dispute_principal` + `dispute_interest` + `dispute_fees`), or does not reconcile with the prior day’s `dispute_balance` plus current dispute transaction activity. Learn More	Verify `dispute_balance` equals the sum of its component fields and reconciles with the prior day’s value plus today’s dispute transactions.
`unexpected_dispute_fee`	The `dispute_fees` does not reconcile with the prior day’s `dispute_fees` plus current dispute transaction activity affecting fees. Learn More	Verify `dispute_fees` equals the prior day’s value plus net dispute activity for fees.
`unexpected_dispute_interest`	The `dispute_interest` does not reconcile with the prior day’s `dispute_interest` plus current dispute transaction activity affecting interest. Learn More	Verify `dispute_interest` equals the prior day’s value plus net dispute activity for interest.
`unexpected_dispute_principal`	The `dispute_principal` does not reconcile with the prior day’s `dispute_principal` plus current dispute transaction activity affecting principal. Learn More	Verify `dispute_principal` equals the prior day’s value plus net dispute activity for principal.
`unexpected_interest_balance`	The `interest_accrued_balance` does not reconcile with the prior day’s `interest_accrued_balance` plus current interest accrual transaction activity. Learn More	Verify `interest_accrued_balance` equals the prior day’s value plus net interest accrual activity from today’s transactions.
`unexpected_reward_balance`	The `rewards_balance` does not reconcile with the prior day’s `rewards_balance` plus current rewards transaction activity. Learn More	Verify `rewards_balance` equals the prior day’s value plus net rewards activity from today’s transactions.

Transactions

Error Code	Description	How to Resolve
`funding_fee_amount_mismatch`	The `fee_amount` does not match the `other_fees.borrower_origination_fee_amount` on the associated Funding object. Applies to transactions with `type` = `disbursement`, `transfer_type` = `internal_transfer`, and `funding_id` is populated. Learn More	Verify that `fee_amount` equals `other_fees.borrower_origination_fee_amount` on the associated Funding object.
`funding_transaction_principal_amount_mismatch`	The `principal_amount` on the transaction does not match the sum of principal amounts on the funding object referenced by `funding_id`. Learn More	Verify that `principal_amount` equals the total principal amount on the associated funding object. Correct the transaction so it matches the funding record.
`outstanding_card_balance_activity_mismatch`	The outstanding card balance does not reconcile with transaction activity. Balance (T) must equal Balance (T-1) plus net transaction activity. Learn More	Verify the balance reflects all transactions from today’s file and reconcile any differences.
`total_charged_off_amount_mismatch_card_balance`	The total charged-off amount across transactions does not match the `charge_off_balance` in the card balance. Learn More	Verify the sum of all charge-off transactions equals the `charge_off_balance` field. Correct either the transactions or the balance.
`total_interest_transaction_amount_mismatch_card_balance`	The total interest transaction amount does not match the interest component in the card balance. Learn More	Verify the sum of interest transactions equals the interest component in the balance. Correct.
`total_payment_transaction_amount_mismatch_card_balance`	The total payment transaction amount does not match the payment component in the card balance. Learn More	Verify the sum of payment transactions equals the payment component in the balance. Correct.
`total_reward_transaction_amount_mismatch_card_balance`	The total reward transaction amount does not match the rewards component in the card balance. Learn More	Verify the sum of reward transactions equals the `rewards_balance` in the balance. Correct.
`total_transaction_amount_mismatch_balance`	The sum of all transaction amounts for this account does not match the balance. Learn More	Verify that the net sum of all transactions for this account equals the reported balance change. Correct the balance or transactions.
`transaction_already_exists`	A transaction with this `client_transaction_id` has already been successfully processed. Duplicate transaction IDs are not allowed across submissions. Learn More	Remove the duplicate record. If this is a new transaction, assign a unique `client_transaction_id`.
`transaction_and_balance_currency_mismatch`	The transaction currency does not match the currency of the associated balance. Learn More	Ensure the `currency` field on the transaction matches the `currency` of the balance it references.
`transaction_balance_credit_amount_mismatch`	The sum of credit transaction amounts for this balance does not match the balance’s credit component. Learn More	Reconcile the credit transactions against the balance credit component and correct any discrepancies.
`transaction_balance_fees_amount_mismatch`	The sum of fee transaction amounts for this balance does not match the balance’s fees component. Learn More	Reconcile the fee transactions against the balance fees component and correct any discrepancies.
`transaction_balance_interest_amount_mismatch`	The sum of interest transaction amounts for this balance does not match the balance’s interest component. Learn More	Reconcile the interest transactions against the balance interest component and correct any discrepancies.
`transaction_balance_payment_amount_mismatch`	The sum of payment transaction amounts for this balance does not match the balance’s payment component. Learn More	Reconcile the payment transactions against the balance payment component and correct any discrepancies.
`transaction_balance_reward_amount_mismatch`	The sum of reward transaction amounts for this balance does not match the balance’s rewards component. Learn More	Reconcile the reward transactions against the balance rewards component and correct any discrepancies.
`transaction_balance_transaction_amount_mismatch`	The total transaction amount for this balance does not match the expected net balance change. Learn More	Reconcile all transaction amounts for this balance and ensure the net change matches the reported balance movement.
`transaction_missing_balance`	No balance record was found for the transaction’s associated account on the file date. Learn More	Ensure a balance record exists for the account before submitting transactions.
`transaction_missing_card_balance`	No card balance record was found for this transaction. Learn More	Ensure a card balance exists for the referenced card before submitting transactions.
`transaction_on_unknown_balance`	The transaction references a `balance_id` that does not correspond to any known balance. Learn More	Verify the `balance_id` on the transaction is correct and that the balance was successfully processed before submitting this transaction.

Transactions Update

Error Code	Description	How to Resolve
`transaction_update_target_is_missing`	The `transaction_id` in the Transactions Update file does not match any previously submitted transaction. A settlement date update can only be applied to a transaction that has already been successfully processed. Learn More	Verify the `transaction_id` is correct and that the original transaction was submitted and processed in a prior Transactions file before submitting an update.

Collaterals

Error Code	Description	How to Resolve
`collateral_account_invalid_status`	The account referenced in the Collateral file does not have a valid status for this operation. Learn More	Verify the referenced account is in `active` status before submitting collateral.
`collateral_account_not_found`	The `account_id` in the Collateral file does not match any known account. Learn More	Verify the `account_id` is correct and that the account exists in the system before submitting collateral.
`collateral_balance_account_id_mismatch`	The `account_id` in the Collateral file does not match the `account_id` on the referenced balance. Learn More	Ensure the collateral record’s `account_id` matches the account associated with the referenced balance.
`collateral_balance_invalid_status`	The collateral’s referenced balance does not have a valid status for this operation. Learn More	Verify the referenced balance has `active` status before submitting collateral.
`collateral_balance_not_deposit_type`	The referenced balance is not of type `deposit`. Collateral records with `type` of `deposit_balance` must reference a deposit-type balance. Learn More	Ensure the `balance_id` references a balance with `type` of `deposit`.
`collateral_balance_not_found`	The `balance_id` in the Collateral file does not match any known balance. Learn More	Verify the `balance_id` is correct and that the referenced balance exists before submitting collateral.
`collateral_balance_too_many_active_collaterals`	Too many active collateral records exist for this balance. The allowed limit has been exceeded. Learn More	Review the active collateral records for this balance and ensure only the permitted number are in `active` status.
`collateral_immutable_field_changed`	An immutable field in the collateral record has changed from a prior submission. Learn More	Restore the immutable field values to match prior submissions. Contact your Technical Account Manager if a correction is required.

Foundations

File Guides

Introduction

Overview of File Validation Errors

File Integrity

Error Codes

Field Format

Error Codes

Business Rules

Error Codes

Accounts

Balances

Transactions

Collaterals

Program Configuration

How to Resolve

Cross-File Reconciliation

Error Codes

Applications

Accounts

Authorized Users

Cards

Balances

Transactions

Transactions Update

Collaterals

​Introduction

​Overview of File Validation Errors

​File Integrity

​Error Codes

​Field Format

​Error Codes

​Business Rules

​Error Codes

​Accounts

​Balances

​Transactions

​Collaterals

​Program Configuration

​How to Resolve

​Cross-File Reconciliation

​Error Codes

​Applications

​Accounts

​Authorized Users

​Cards

​Balances

​Transactions

​Transactions Update

​Collaterals

Introduction

Overview of File Validation Errors

File Integrity

Error Codes

Field Format

Error Codes

Business Rules

Error Codes

Accounts

Balances

Transactions

Collaterals

Program Configuration

How to Resolve

Cross-File Reconciliation

Error Codes

Applications

Accounts

Authorized Users

Cards

Balances

Transactions

Transactions Update

Collaterals