When something goes wrong

Common troubleshooting

What each refusal means, why it happens, and how to fix it. Start from the answer you got - the same for every language.

You will needThe answer your code got: its status, and the message or errors in it.
By the endThe cause of the problem, and what to change.

1Start from the answer

Every refusal says what went wrong in its message, and a refused write also lists each problem under errors, with a field, a code and a detail. Find the answer you got below.

What each answer means
Start from the answer you got: it says what was tried, and whether anything was written.

2Signing in is refused

These come back from POST /tokens or POST /tokens/refresh:

401 - The client id and secret do not match.A setting is wrong: check BRIZO_CLIENT_ID and BRIZO_CLIENT_SECRET for a typing error or a stray space. The secret is shown only once; if it's lost, create a new credential.
401 - This credential is revoked or has expired.Create a new credential.
401 - The refresh token is no longer valid.A refresh token works once and lasts 30 days. Sign in again with the client ID and secret - the tutorials' client does this for you.
401 - The account that owns this credential no longer exists.The person who created the credential no longer has an account. Someone who administers data on the group creates a new one.
403 - The API is available on the Premium edition.The group isn't on the Premium plan.
429More than 10 sign-ins in a minute from the same address. Sign in once, and use the access token for its 60 minutes.

3A call is refused with 401 or 403

401 - Unauthenticated.The access token has run out after 60 minutes, or wasn't sent. Renew it with the refresh token and send the call again - the tutorials' call() does this once for every call.
403 - This credential does not hold the … scope.The box for this was not ticked on the credential. A credential can't be changed: create a new one with the box ticked, and revoke the old one.
403 - This credential may not call from this address.The credential has Allowed IP addresses, and the call came from another one. Add the address on a new credential, or call from a listed one.
403 - This credential is revoked or has expired.It was revoked, or reached its expiry date, after you signed in. Create a new credential.
403 - This account may no longer administer data for this organisation.A credential acts with the rights of the person who created it. That person can no longer administer data on the company, so writes are refused. Reads need the right to report on it.
403 - The API is available on the Premium edition.The group has left the Premium plan.

4A company answers 404

No such organisation. means the credential wasn't issued for that organisation. The answer is the same as for an organisation that doesn't exist, so an ID can't be probed.

  • Check the ID: GET /organisations lists every organisation the credential was issued for, with its ID.
  • The group answers only when it is ticked on the credential, under Organisations it may use; otherwise its ID answers 404 like any other organisation the credential was not issued for.
  • To reach another company, or the group, create a credential with it ticked.

5A call answers 429

Nothing was written for that call. Wait as many seconds as Retry-After says, then send it again. There are two reasons:

write_in_flightAnother write is running for the same company. BrizoConsol writes one at a time for a company, and asks you to wait 5 seconds. Send one company's writes one after another.
No codeYour group has used its requests for the minute: 60 by default, shared by every credential in the group.

6The whole write is refused

The answer is 422, nothing was written, and each problem is listed under errors. Fix it and send again:

base_currency_disagreesbase_currency isn't the company's own currency. The detail names the right one; GET /organisations lists it too.
period_lockedThe month is behind a period lock in BrizoConsol. Someone has to unlock it first.
period_outside_windowThe month is outside the range of months your plan allows actual figures for. The detail names the range. Budgets and forecasts aren't bound by it.
month_held_by_another_sourceFor a trial balance: another source - a connected accounting system, an upload - already holds the month. To take it over, send it again with switch_source. For journal lines: another source_reference already holds the month's lines.
cap_exceededThe company would hold more than its limit - of accounts, or of a month's invoices, bills, journal lines or operational rows. The detail gives the limit and the total the request would leave.
invalid_valueA declaration isn't one of the values allowed, such as mode, value_basis or rate_direction. The detail lists them.
Two kinds of refusal
A request refused whole writes nothing. Records refused one by one leave the rest written.

7Some records are refused

The answer is 202 and the rest was written, but counts.rejected is above zero. Ask GET …/requests/{id}/results for each record's outcome. The reasons you are most likely to see:

account_not_foundThe account code isn't in the company's chart. Send the chart first, or correct the code.
journal_does_not_balanceA journal's debits and credits differ. Every line of that journal is refused.
amount_disagrees_with_totalAn invoice's or bill's lines don't add up to its total.
rate_required_for_foreign_currencyA document in a currency other than the company's has no exchange rate.
duplicate_record_identityTwo records in the same request have the same identity, such as the same account code or invoice ID.
unknown_fieldA field the API doesn't have. Check its spelling against the endpoint's documentation.

A trial balance month is sent whole, so a refused line leaves the month without it. Fix it and send the whole month again, with a new Idempotency-Key.

8A send wrote nothing

If Idempotency-Key was already used, BrizoConsol answers with the first request and writes nothing, even if the figures in the body are different. Change the key whenever the figures change.

9The reports don't show what you sent

  • They're rebuilt overnight. Figures are stored when you send them, and the reports are rebuilt by the overnight run at 01:40. Until then, a trial balance request reads recalculation: pending. Read the reports the next morning, once it reads done.
  • The reporting month moved. Sending a month's trial balance sets the group's reporting month to that month - also when it's earlier than before.

10The webhook never arrived

  • It's called once, when the write finishes - not when the overnight run does.
  • The address must be public: a private or internal address isn't called, and redirects aren't followed.
  • A call that fails never fails the request. Read the request back to see what happened.

Want more detail? See the documentation