Errors

Every refusal is a JSON body with a single message, and a status code that says what kind of thing went wrong.

{ "message": "This credential may not call from this address." }

401 — the caller is not who it says

MessageWhat it means
The client id and secret do not match.The exchange was given a client id or secret that does not exist
This credential is revoked or has expired.Revoked on the screen, or past its expiry date
The refresh token is no longer valid.Refreshed twice with one token, or it has expired
The account that owns this credential no longer exists.The creator’s account was removed

403 — the caller is known, but not allowed

MessageWhat it means
This token was not issued by an API credential.The bearer token predates the credential exchange, or is not from this API
This credential is revoked or has expired.Same credential, seen on a normal call rather than the exchange
This credential may not call from this address.The call’s address is outside the credential’s allowlist
This credential may not write {kind}.The credential holds no {kind}.write scope
This credential does not hold the {scope} scope.A read whose credential holds no {resource}.read scope
This account may no longer administer data for this organisation.The account behind the credential lost its data-admin right on that organisation
This account may no longer report on this organisation.A read, where the account behind the credential lost its reporting right on that organisation
This token may not write.The token was issued without the write ability
This token may not read.The token was issued without the read ability

404 — the path or the record does not exist

The API never confirms that an organisation the credential may not use exists: an organisation that is not ticked on the credential answers the same 404 as one that does not exist at all, for a read and for a write alike.

{ "message": "No such organisation.", "code": "not_found" }

The schema endpoint answers a kind it does not carry by name, and lists the kinds it does carry:

{ "message": "No such kind.",
  "kinds": ["accounts", "trial_balance", "invoices", "bills", "transactions", "operation_data"] }

422 — the request was refused on its contents

The write endpoints refuse an invalid body in the same shape as the schema's own validation:

{ "message": "The request was refused.",
  "errors": [{ "index": 3, "field": "records.3.amount_base", "code": "invalid_type", "detail": "…" }] }

A read refuses a parameter in the same envelope, with the field that was wrong and no record index, because a read has no records:

{ "message": "The request was refused.",
  "errors": [{ "field": "number_of_months", "code": "invalid_value",
               "detail": "0 is not a number of months. Ask for 1 to 120." }] }

A read uses the codes the write side publishes: invalid_value for a value outside what the endpoint takes, required_field_missing for one it needs - section on a detail read - and unknown_field for a parameter the resource does not take, which is refused rather than ignored so no caller believes a filter applied.

A body that passed its checks and then failed while writing answers with the code that failed, and stays readable at its own URL:

{ "message": "The request failed.",
  "failure": { "code": "journal_does_not_balance", "errors": [ … ] } }

429 — too many requests

Token requests are limited to 10 a minute per caller. Data requests are limited per group, at the group's own requests-per-minute figure - a second token or a second credential does not buy a second allowance.

Ten failed token exchanges from one address within 30 minutes - a client id and secret that do not match - lock that address out of token requests until 30 minutes after the first of them. The exchange then answers 429 with "Too many failed attempts from this address. Try again later." and a Retry-After header giving the seconds left.

429 also answers a write that arrives while another write for the same company is still running, with code write_in_flight and a Retry-After header. Nothing is written for that call, so send it again once the first has finished; no need to check what landed first. See Limits.