# Bank import and close refusal codes

> The finance engine refuses before it writes. Each refusal returns a code and the figures that explain it, so an agent can tell the operator what to do rather than what went wrong. None of these leaves a half-written state: a refused import writes zero rows, a refused close writes no row, a refused split writes nothing.

URL: https://biloh.com.au/docs/reference/bank-import-and-close-refusal-codes
Category: Reference | Audience: agent | Updated: 2026-10-26

**At a glance**

- **Who it's for:** AI assistants working in a Biloh business
- **What it does:** [The bank feed reconciled for you](https://biloh.com.au/capabilities/bank-reconciliation) · [Books and BAS, ready for your accountant](https://biloh.com.au/capabilities/bookkeeping-and-bas)
- **Tools it uses:** [`import_bank_csv`](https://biloh.com.au/connect#import_bank_csv) · [`create_bank_account`](https://biloh.com.au/connect#create_bank_account) · [`run_period_close`](https://biloh.com.au/connect#run_period_close) · [`run_month_end_close`](https://biloh.com.au/connect#run_month_end_close) · [`match_bank_credit_to_invoice`](https://biloh.com.au/connect#match_bank_credit_to_invoice) · [`get_reconciliation_suggestions`](https://biloh.com.au/connect#get_reconciliation_suggestions) · [`triage_bank_feed`](https://biloh.com.au/connect#triage_bank_feed) · [`link_bank_credit_to_existing_payment`](https://biloh.com.au/connect#link_bank_credit_to_existing_payment) · [`split_bank_transaction`](https://biloh.com.au/connect#split_bank_transaction) · [`triage_bank_transaction`](https://biloh.com.au/connect#triage_bank_transaction) · [`update_expense_record`](https://biloh.com.au/connect#update_expense_record) · [`confirm_shoebox_pairing`](https://biloh.com.au/connect#confirm_shoebox_pairing) · [`get_bas_worksheet`](https://biloh.com.au/connect#get_bas_worksheet) · [`record_bill`](https://biloh.com.au/connect#record_bill) · [`settle_bill_with_bank_debit`](https://biloh.com.au/connect#settle_bill_with_bank_debit) · [`create_asset`](https://biloh.com.au/connect#create_asset) · [`mark_obligation_lodged`](https://biloh.com.au/connect#mark_obligation_lodged) · [`reopen_period`](https://biloh.com.au/connect#reopen_period) · [`get_period_ladder`](https://biloh.com.au/connect#get_period_ladder)
- **What a person approves:** Biloh never moves money: its tools record payments that already happened, and a pay-now link opens the business's own Stripe checkout for its client. · Every change is recorded, with who made it and when. · Your business records are stored in Sydney, Australia.
- **Checked against the code:** 2026-09-18

## Bank feed

| Code | Tool | Meaning | Comes with | Next step |
| --- | --- | --- | --- | --- |
| `wrong_account_or_gap` | `import_bank_csv` | The file's implied opening balance does not chain onto the account | Expected and actual balances; zero rows written | Wrong file for this account, or a missing window: export the right days |
| `override_reason_required` | `import_bank_csv` | `override_chain_gap` was set with an empty reason | Nothing imported | Give a reason; the override is audit-logged |
| `identifier_not_masked` | `create_bank_account` | A full account number or BSB was supplied | Nothing stored | Supply the last four digits only |
| `bank_completeness_failed` | `run_period_close`, `run_month_end_close` | A line in the range fails to tie by running balance | First break's date and the gap in cents; no row written | Import the missing window, or sign off over the gap with a reason |
| `needs_variance_reason` | `run_period_close` | A peer total was passed and differs from Biloh's received figure | `variance_cents`, `received_cents` | Explain the variance in `variance_reason` and retry |

## Money in

| Code | Tool | Meaning | Next step |
| --- | --- | --- | --- |
| `already_matched` | `match_bank_credit_to_invoice` | This deposit has already paid an invoice; the payment is keyed to the deposit so it can never pay twice | Nothing to do, or unmatch first if the earlier match was wrong |
| `already_paid` (warning) | `get_reconciliation_suggestions`, `triage_bank_feed` | The candidate invoice is settled and is offered only because the bank text names it | Usually `link_bank_credit_to_existing_payment` |
| `amount_mismatch` (warning) | same | The deposit and the invoice differ in amount | A part payment, split or fee: match knowingly, or decide otherwise |

## Money out

| Code | Tool | Meaning | Next step |
| --- | --- | --- | --- |
| `split_total_mismatch` | `split_bank_transaction` | The splits do not sum to the line; the message names the gap in cents | Correct the amounts |
| `gst_exceeds_one_eleventh` | `split_bank_transaction`, `triage_bank_transaction`, `update_expense_record` | The stated GST is more than one eleventh of the amount, rounded to the nearest cent (19413 allows at most 1765) | Correct the GST to the figure printed on the paper |
| `gst_requires_evidence` | `split_bank_transaction` | A split claims GST with no document and no attestation | Attach the receipt or state where the paper is |
| `invalid_expense_payload` | `split_bank_transaction` | An impossible GST and treatment pair | Correct the pair |
| `already_split`, `bank_txn_already_matched`, `split_requires_debit`, `category_not_found` | `split_bank_transaction` | State refusals | Unsplit or unmatch first; use a debit; use a listed category |
| `bank_line_not_debit` | `confirm_shoebox_pairing` | A receipt substantiates money going out, not in. Only a supplier's adjustment note (or credit note) pairs to a credit | Pair the receipt against a debit |
| `adjustment_note_mismatch` | `confirm_shoebox_pairing` | An adjustment note whose amount or supplier does not match the credit | Pair it to the credit for exactly its amount |
| `refund_gst_unclaimed` (BAS contradiction) | `get_bas_worksheet` | A supplier-looking credit is coded with no GST while an exact-match adjustment note waits; `headline_safe` is false | Code the credit to `purchase-refund` with the note's GST and the note as `document_id` |
| `already_exited` | `confirm_shoebox_pairing` | The receipt already left as a cash expense | Unpick that expense first if it was wrong |
| GST on an unregistered contractor | `record_bill` and settlement tools | The contractor is not GST-registered and the bill claims GST | Governed by `finance.ap.unregistered_gst_enforcement`; correct the bill |
| Out-of-gate settlement | `settle_bill_with_bank_debit` | The linked client invoice is unpaid | Governed by `finance.ap.out_of_gate_settlement`: warn or refuse |
| Paid date in a closed period | settlement tools | The debit's value date falls inside a closed period | Reopen the period with a reason first |

## Assets

| Code | Tool | Meaning | Next step |
| --- | --- | --- | --- |
| Instant write-off above threshold | `create_asset` | The cost exceeds `finance.assets.instant_writeoff_threshold`; the refusal names the threshold | Choose diminishing value or prime cost with an effective life |
| Debit already minted an asset | `create_asset` | One debit mints one asset | Split the line first if it bought two things |

## Obligations

| Code | Tool | Meaning | Next step |
| --- | --- | --- | --- |
| Receipt required | `mark_obligation_lodged` | No lodgement receipt document was named | Record the receipt in the evidence layer, then lodge with its id |

## Periods

| Code | Tool | Meaning | Next step |
| --- | --- | --- | --- |
| Not closed | `reopen_period` | The period was never closed | Nothing to reopen; make the change |
| `child_period_open` | `run_period_close` | A quarter or FY is the sum of its months and one is not closed (`open_child_months` names them) | Close the named months, then the quarter or FY |
| `stale` (state) | `get_period_ladder` | A child was reopened after this period closed | Re-close the parent |

## Cross-cutting

| Code | Where | Meaning |
| --- | --- | --- |
| `expected_tenant_mismatch` | any tool | The `expected_tenant` assertion did not match the connection's tenant; nothing ran. See [write safety](/docs/reference/write-safety-expected-tenant) |
| `upgrade_required` | tier-gated tools | The capability is not in this business's plan |

## Related

- [The balance chain](/docs/concepts/the-balance-chain)
- [Finance MCP tools](/docs/reference/finance-mcp-tools)