One of the most complicated aspects of QuickBooks Desktop is its error handling. QuickBooks errors are often cryptic and unhelpful, and they can arise from several sources (e.g., Web Connector, QB request processor, QuickBooks Desktop itself), each using a different format and mechanism. Sometimes, their errors do not even describe what went wrong when they could! Conductor unifies and simplifies these errors into a single, consistent error format and augments each with our own user-friendly language that describes how to resolve the issue.

With Conductor, every error includes plenty of useful information.

​

Error types

Any error object you receive will be an instance of one of the following error types:

​

Common error codes

​

User-facing error messages

Every Conductor error includes two error messages, and you should use both:

1. error.message: The technical error message that you should log for debugging.
2. error.userFacingMessage: The descriptive user-friendly error message explicitly written for the end-user that often contains instructions helping the end-user resolve the issue.

For example, see the message and userFacingMessage in the following QBD connection error:

{
  "error": {
    // The developer-facing error message, which includes the QBD-provided
    // error code and the QBD-provided error message.
    "message": "QBD Connection Error (0x80040420): The QuickBooks user
      has denied access.",
    // The user-facing error message with instructions for the end-user to
    // resolve the issue.
    "userFacingMessage": "We could not connect to QuickBooks Desktop
      because we must re-authorize our connection. To fix this, open
      QuickBooks Desktop, log in as Admin, navigate to 'Edit >
      Preferences → Integrated Applications', click 'Company Preferences',
      select our app, click 'Properties...', ensure 'Allow this
      application to log in automatically' is checked, then click 'OK'.
      Then try again.",
    "type": "INTEGRATION_CONNECTION_ERROR",
    "code": "QBD_CONNECTION_ERROR",
    "httpStatusCode": 502,
    "integrationCode": "0x80040420",
    "requestId": "req_1234567890"
  }
}

​

Error handling in our SDKs

Our errors in our SDKs are a bit janky at the moment. We’re working on it. For now, we recommend the approach shown below for typing and unwrapping Conductor errors from our SDK. The example below is for our Node.js SDK, but the approach would be similar for our Python SDK.

import Conductor, { APIError as ConductorError } from "conductor-node";

// Yes, manually define this inline.
interface IConductorError {
  message: string;
  userFacingMessage: string;
  type: string;
  code: string;
  httpStatusCode: number;
  integrationCode?: string;
  requestId: string;
}

const conductor = new Conductor({ apiKey: "{{YOUR_SECRET_KEY}}" });

try {
  // Check the connection status
  await conductor.qbd.healthCheck({ conductorEndUserId: "{{END_USER_ID}}" });
  updateUI("QuickBooks Desktop is successfully connected!");
} catch (error) {
  if (error instanceof ConductorError) {
    // Unwrap Conductor error
    const conductorError = error?.error?.error as IConductorError;

    if (conductorError.code === "INTEGRATION_CONNECTION_NOT_SET_UP") {
      // This specific error code indicates the user needs to go through the auth
      // flow. Either they never started it, or didn't complete it.
      const authSession = await conductor.authSessions.create({
        publishableKey: "{{YOUR_PUBLISHABLE_KEY}}",
        endUserId: "{{END_USER_ID}}",
      });
      updateUI(
        "Set up your QuickBooks Desktop connection: " + authSession.authFlowUrl,
      );
    } else {
      // Display connection errors for your user to resolve.
      updateUI("An error occurred: " + conductorError.userFacingMessage);
    }
  } else {
    throw error;
  }
}

​

Specific error handling

If you need special handling for specific errors, you can wrap individual API calls, as shown below.

Using async/await:

import Conductor, { APIError as ConductorError } from "conductor-node";

const conductor = new Conductor({ apiKey: "{{YOUR_SECRET_KEY}}" });

try {
  const newAccount = await conductor.qbd.accounts.create({
    conductorEndUserId: "end_usr_1234567abcdefg",
    accountType: "bank",
    name: "Accounts-Payable",
  });
} catch (error) {
  if (error instanceof ConductorError) {
    // Unwrap Conductor error
    const conductorError = error?.error?.error;
    // Check `conductorError.code`, `conductorError.integrationCode`, etc., for special handling.
  } else {
    // ...
  }
}

Or in the form of a rejected promise:

import Conductor, { APIError as ConductorError } from "conductor-node";

const conductor = new Conductor({ apiKey: "{{YOUR_SECRET_KEY}}" });

conductor.qbd.accounts
  .create({
    conductorEndUserId: "end_usr_1234567abcdefg",
    accountType: "bank",
    name: "Accounts-Payable",
  })
  .then((newAccount) => {
    // ...
  })
  .catch((error) => {
    if (error instanceof ConductorError) {
      // Check `error.code`, `error.integrationCode`, etc., for special handling.
    } else {
      // ...
    }
  });

​

Global error handling

It is unnecessary to wrap each API call individually, as demonstrated in the examples above. Instead, we suggest implementing a global error handler for your server, such as app.use((error, ...) => { ... }) in Express. Within this handler, perform the following actions:

1. For any ConductorError instance, display the error.userFacingMessage property to the end-user in your app’s UI while logging the complete error object.
2. For all ConductorError instances, transmit the full error object to your error-tracking service (e.g., Sentry):
   • Send a warning for instances of INTEGRATION_CONNECTION_ERROR, which are not actionable by you and can only be resolved by the end-user; for example, failure to connect to QuickBooks Desktop on the end-user’s computer.
   • Send an error for all other ConductorError instances, such as an invalid API key.

For example, using an Express error handler:

import * as Sentry from "@sentry/node";
import Conductor, { APIError as ConductorError } from "conductor-node";

const conductor = new Conductor({ apiKey: "{{YOUR_SECRET_KEY}}" });

app.use((error, req, res, next) => {
  if (error instanceof ConductorError) {
    // Unwrap Conductor error
    const conductorError = error?.error?.error as IConductorError;

    Sentry.captureException(error, {
      level:
        conductorError.type === "INTEGRATION_CONNECTION_ERROR"
          ? "warning"
          : "error",
    });
    // Return a different error message for your end-user to see in your
    // app's UI.
    res
      .status(500)
      .send({ error: { message: conductorError.userFacingMessage } });
  } else {
    // ...
  }
});