QuickBooks: errors that are temporary, and when not to re-authorize

Some QuickBooks Online errors look like a broken connection or a permissions problem, but are actually temporary issues on Intuit's side. Re-authorizing doesn't help with these. Retrying after a short pause does. This article helps you tell them apart. The same applies to Intuit Enterprise Suite.

QuickBooks locks a company file briefly when two requests reach it at the same moment. You'll see one of these:

• a 400 with a QuickBooks SystemFault

• a 401 with error code 100 or 140

• a message saying the company is locked out (LOCKED_BY_SERVER)

What to do: wait a few seconds and retry. Apideck recognises these as temporary, so they don't break the connection and no re-authorization is needed. To avoid them, don't send many requests in parallel to the same QuickBooks company.

Sometimes one record type fails with a 400, error code 5020: *"Permission Denied Error … Missing permission on CreditMemo to Read"* (or another record type). At the same moment, other record types on the same connection still work.

If other record types work, it isn't a problem with the connection or its permissions. A real permission or connection problem would affect every call. Intuit returns this code for several unrelated reasons, often temporary ones on its side.

What to do:

1. Retry later.

2. If one record type keeps failing for a long time while everything else works, check that the customer's QuickBooks subscription includes that feature (some features need a higher QuickBooks plan).

3. Contact Apideck support through the Customer Portal (the Requests link at the top of this help center), your Slack channel with us, or support@apideck.com, with the consumer ID and the time it happened.

During some Intuit incidents, QuickBooks returns AuthorizationFault / *Access Denied* for a short period, even though the connection's credentials are valid and other calls are going through.

What to do:

• When QuickBooks returns this as a 403, Apideck treats it as a temporary upstream problem and returns a 502. Retry later.

• If a connection shows as needing authorization during such an incident, check whether it was still serving successful calls around the same time. If it was, it usually recovers by itself once QuickBooks responds normally again, so don't ask your customer to re-authorize straight away.

• The token refresh fails, and you receive a vault.connection.token_refresh.failed webhook. See Token Refresh Lifecycle Events.

• Every call to the connection fails, not just one record type.

• The customer disconnected the app in QuickBooks, or the user who connected it lost access.

See Why did my connection stop working? for the full list.

• QuickBooks: What is the purpose of the "realm_id" property?

• Rate limits: understanding 429 errors