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.
message or errors in it.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.
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. |
| 429 | More 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 /organisationslists 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_flight | Another 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 code | Your 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_disagrees | base_currency isn't the company's own currency. The detail names the right one; GET /organisations lists it too. |
|---|---|
| period_locked | The month is behind a period lock in BrizoConsol. Someone has to unlock it first. |
| period_outside_window | The 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_source | For 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_exceeded | The 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_value | A declaration isn't one of the values allowed, such as mode, value_basis or rate_direction. The detail lists them. |
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_found | The account code isn't in the company's chart. Send the chart first, or correct the code. |
|---|---|
| journal_does_not_balance | A journal's debits and credits differ. Every line of that journal is refused. |
| amount_disagrees_with_total | An invoice's or bill's lines don't add up to its total. |
| rate_required_for_foreign_currency | A document in a currency other than the company's has no exchange rate. |
| duplicate_record_identity | Two records in the same request have the same identity, such as the same account code or invoice ID. |
| unknown_field | A 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 readsdone. - 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