Skip to main content
When a Balance or Transaction file fails validation, the 🔴 Slack alert names the error code, the failing detail, and the action to take. This page covers the most common failures symptom-first; the complete catalog is File Submission Validation Errors. The universal recovery loop: fix the flagged records, upload a new version of the corrected file (same batch), and Lead re-validates the latest version of each file in the batch. Resubmit before the next cycle where possible so one bad day doesn’t cascade into the next day’s T−1 checks.
Error code renames effective August 4, 2026. Several balance-related codes dropped the legacy account_balance term (e.g., transaction_missing_account_balance → transaction_missing_balance; balance_cannot_be_closed_with_processing_funding → balance_cannot_be_terminal_with_processing_funding). If your automation keys off code strings, use the new codes — the changelog entry has the full mapping.
Symptom: errors like unexpected_balance, unexpected_past_due_balance, unexpected_dispute_balance, or unexpected_charge_off_balance. The alert detail shows the expected sum, your submitted value, the delta, and the Sample ID of a failing record — e.g., balance (316125.78) was expected to be 316124.78 (delta: 1.00), the sum of outstanding_principal, outstanding_interest, and outstanding_fee.Likely causes: a component field out of sync with the total (rounding, a fee booked to the wrong bucket); or the day’s transactions don’t account for the balance movement, breaking the invariant balance(T) = balance(T−1) + T’s transactions.How to confirm: pull the Sample ID’s record from your file, recompute the named components, then recompute the invariant against yesterday’s submitted balance and today’s transactions for that balance_id.Fix: correct the component or add the missing transaction, resubmit the file version. Prevention: assert both identities in your pipeline before submission (Balance Reconciliation).
Symptom: transaction_missing_balance / transaction_missing_card_balance (pre-Aug-4: …_account_balance), or — for card programs — previous_active_card_balance_missing.Likely causes: the transaction’s balance_id was never established in a Balance file (or, for credit, never created via the Subledger Balance API); files arrived out of order so the transaction landed before its balance; or a card balance active yesterday is absent from today’s file.How to confirm: search your Balance submissions for the balance_id; check whether today’s Balance file includes every balance that was active on T−1.Fix: establish or re-include the balance, then resubmit the transaction file. Balances don’t disappear when quiet — an active balance is reported every day until you transition it per Balance Statuses.
Symptom: account-linkage validation failure on new Balance creation.Cause: every Balance must reference a valid parent Account; enforcement begins October 6, 2026 (Upcoming Changes).How to confirm: GET /v0/accounts/{id} for the referenced account_id — it must exist and its capabilities must permit the balance type (deposit capability for deposit balances; a credit capability for credit balances).Fix: create the account first (Entity → [Application →] Account), or correct the account_id in your file generation, before the balance is submitted. Review your workflows ahead of October 6.
Symptom: transaction_activity_check / transaction_type_invalid_activity_check.Cause: each transaction type constrains which amount fields may be non-zero: disbursement — principal_amount > 0; interest_amount and fee_amount = 0 · interest_accrued — interest_amount > 0; others = 0 · fee — fee_amount > 0; others = 0.Fix: split composite entries into one transaction per type rather than packing principal, interest, and fees into one record. Valid type/action/transfer-type combinations: Transaction Types.
Symptom: funding_fee_amount_mismatch on a disbursement transaction.Cause: when a transaction has type: disbursement, transfer_type: internal_transfer, and a populated funding_id, its fee_amount must equal other_fees.borrower_origination_fee_amount on that Funding.How to confirm: GET /v0/fundings/{funding_id} and compare.Fix: correct whichever side is wrong — usually the file; the Funding’s fee was fixed at creation (The Funding Object).
Symptom: balance_cannot_be_terminal_with_processing_funding.Cause: you reported a balance into a terminal status (closed, or receivable_transferred) while a Funding against it is still processing.Fix: wait for the Funding to reach posted or rejected (the funding.posted webhook, or Simulate Advance Funding in sandbox), then report the terminal status.
Symptom: no 🟢 or 🔴 for a submission.Likely causes: file delivered after the 6:00 a.m. CT cutoff, so it missed the day’s cycle; wrong SFTP path (alerts now include the full file path — check it matches the expected folder); or a filename outside the convention (epoch-timestamp generation time or v1/v2 version suffix — SFTP setup).Fix: correct path/naming and resubmit; if the cutoff was missed, coordinate with your Lead team on whether the file can join today’s cycle or must roll. Remember empty days still require an empty file.
Still stuck? Escalate in your Slack channel with the full file path from the alert, the error code, and the Sample ID — that trio lets Lead locate the exact record immediately.