Documentation Index
Fetch the complete documentation index at: https://docs.lead.bank/llms.txt
Use this file to discover all available pages before exploring further.
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
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
2. Record Evaluation in the Same File
| 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
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_usdmust 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
statustostatus_reasonpairings (e.g., in the Accounts schema, a “closed” status must pair withentity_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_signersare required whenaccount_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_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 a 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-1Learn 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_idmust 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_usdis 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_idrequirements 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_idandcard_idmust 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 | 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_closed_with_processing_funding | This balance cannot be closed because it has funding in a processing state. Learn More | Wait until all pending funding transactions are settled before closing this balance. |
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. |
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_account_balance_missing | A non-terminal card account balance from the prior day is missing from today’s submission. All non-terminal card account balances must be reported every day. Learn More | Add the missing card account 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 |
|---|---|---|
outstanding_card_account_balance_activity_mismatch | The outstanding card account 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_account_balance | The total charged-off amount across transactions does not match the charge_off_balance in the card account 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_account_balance | The total interest transaction amount does not match the interest component in the card account balance. Learn More | Verify the sum of interest transactions equals the interest component in the balance. Correct. |
total_payment_transaction_amount_mismatch_card_account_balance | The total payment transaction amount does not match the payment component in the card account balance. Learn More | Verify the sum of payment transactions equals the payment component in the balance. Correct. |
total_reward_transaction_amount_mismatch_card_account_balance | The total reward transaction amount does not match the rewards component in the card account balance. Learn More | Verify the sum of reward transactions equals the rewards_balance in the balance. Correct. |
total_transaction_amount_mismatch_account_balance | The sum of all transaction amounts for this account does not match the account 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_account_balance | No account 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_account_balance | No card account balance record was found for this transaction. Learn More | Ensure a card account 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. |