Something will not post
Every reason Books refuses a posting, what each message means, and how to clear it — for manual entries, machine work, and API calls alike.
ReferenceFor Bookkeepers, Firm staff, Developers
Refusal reasons
Books refuses postings rather than accepting them with a warning. The same rules apply through every interface — the workspace, automation, and the API — so a refusal means the same thing wherever you hit it.
| Reason | Meaning | Fix |
|---|---|---|
| Does not balance | Debits and credits differ. | Correct the amounts; check for a value typed in the wrong column. |
| Period locked | The date falls in a closed period. | Re-date into the open period, or reopen the period deliberately. |
| Account missing or archived | A line references an account that does not exist or is retired. | Create, unarchive, or choose a different account. |
| Control account not directly postable | A line targets A/R or A/P. | Use an invoice, bill, payment, or credit memo instead. |
| Required dimension missing | Policy requires a class or location on this account. | Supply the dimension, or change the policy. |
| Vendor or customer not found | Extraction or an API call named a party with no record. | Create the record, or merge if it is a variant of an existing one. |
| Needs approval | Policy requires review before posting. | It is in Approvals — this is not an error. |
| Duplicate suspected | It matches an existing record on the duplicate criteria. | Confirm and dismiss, or override if genuinely distinct. |
| Ambiguous match | A payment could settle more than one document. | Choose the correct match. |
| Entity not in scope | The target entity is outside your access or the key's scope. | Check entity access, or the API key's capabilities. |
Where refusals surface
| Origin | Where it appears |
|---|---|
| Manual entry | Inline on the form, at save. |
| Document intake | On the intake row, or as an exception. |
| Bank categorization | As an exception. |
| Recurring schedule | As an exception, with the occurrence's date. |
| The coworker | In the conversation, with what it was attempting. |
| API | As an error response on the request. |
Was this useful?