Operating notes #
Practical things that come up once the server is connected and in use.
Check the connection #
Ask the assistant to call get_ledger_setup. A good response names your
entity and its reporting currency, lists the configured currencies, and shows
the reporting periods. That one call exercises the token and the network path
together, and it reads
GET /meta, so it
is the quickest way to confirm a working connection.
Reading an error #
Failures come back with the API’s own error taxonomy, and they are worth reading rather than retrying blindly:
- a numeric
detail_codeand ahelpURL pointing at the relevant guide; - for a
422, the offending field and every field that would have been accepted. A misspelled argument tells the assistant exactly what to use instead, so these usually self-correct on the next attempt.
A few that come up often:
| What you see | What it means |
|---|---|
detail_code 103 on a schedule or a close | The account is the wrong type — /account/{id}/schedule wants RECEIVABLE or PAYABLE, and a period close wants an EQUITY forex account |
detail_code 104 | A compound journal entry cannot carry tax |
| "…is already posted and is immutable" | Correct it with a credit note, debit note or journal entry instead of amending |
| "…cannot be deleted because it has Line Items" | Reached through amend_draft’s delete, which detaches lines first — seen directly only via the API |
Previewing before committing #
Every write accepts dry_run=true, which sends the API’s
rollback header:
the real controllers validate the request and the whole thing is then rolled
back. Ids in the response do not exist afterwards.
It is the cheapest way to check a transaction, and worth asking for by name — “dry run that first” — before anything you are unsure about.
Rate limits #
Requests are capped per user per minute; get_ledger_setup reports the
current limit under its limits section, and the API documents the behaviour
under rate limits.
A single assistant working conversationally will not approach it; a bulk
import driven through the assistant might.
Retries and duplicate writes #
The API supports an
Idempotency-Key
header so a retried write replays the original response instead of creating a
second record. The tools do not set one. A key invented per call would be
new on every retry and protect nothing, and one derived from the request
would silently merge two genuinely separate but identical entries — and
recording the same sale twice in a day is perfectly legitimate.
The practical consequence: if a write times out, check with get_transaction
or find_accounts before asking for it again.
Revoking access #
A personal access token can be revoked at any moment from Dashboard → Developers → API tokens; the connection stops working immediately. Revoking is the fastest way to halt an assistant mid-task — faster than editing client config and restarting.