Error handling (systematically and consistently)

[samshdn]

Normally, an application encounters two types of errors: business errors and system errors. A business error occurs when a user provides incorrect input parameters, for example. In such cases, we need to return appropriate information to the user so they understand what went wrong and what actions they should take.

The second type is a system error, such as a network failure. These are considered exceptions. We typically do not send detailed error information back to the user, as they cannot take any meaningful action to resolve it. Instead, we should log these errors for further analysis and troubleshooting.

[samshdn]

According to the concept above, we can design two classes: one for business errors and the other for system errors. Each class should have two attributes: code and message.

class BusinessError extends Error {
  code: string;

  constructor(code: string,message: string) {
    super(message);
    this.code = code;
  }
}

class SystemError extends Error {
  code: string;

  constructor(code: string,message: string) {
    super(message);
    this.code = code;
  }
}

Define error handling middleware

app.onError((err, c) => {
  if (err instanceof BusinessError) {
    // business logic error
    return c.json(
      {
        error: {
          code: err.code,
          message: err.message,
        },
      },
      err.status
    );
  } else if (err instanceof SystemError) {
    // system error
    logger.error('System Error:', err); 
    return c.json(
      {
        error: {
          code: err.code,
          message: 'An unexpected error occurred. Please try again later.',
        },
      },
      err.status
    );
  } else {...}

route example

app.post('/v0/status/:id', async (c) => {

  if (!id) {
    throw new BusinessError(...);
  }

  // database operation
  try {
    // assume there is connection error
    throw new Error('Database connection failed');
  } catch (err) {
    throw new SystemError(...);
  }

  return c.json({ ... });
});

[jduan00]

I believe there are two types of errors:

1. Errors that directly provide feedback to users via HTTP and JSON (I’m still unsure if these are BusinessError?).
2. Errors that are logged internally for debugging purposes. (i.e. Postgres errors #75)

I’ll classify them as externalErrors and internalErrors.

errorCode must be unique within a scope, like a code file. See #55.
errorMessage should be clear and easy to understand. Also by logging each error-triggering request.

Reference:

• Refactor the Errors to distinguish between protocol logic errors and system-level errors. deventlab/d-engine#66
• https://medium.com/deno-the-complete-reference/using-logger-in-deno-44c5b2372bf3

Example:

console.error("Error SCOPE-01: Cannot connect to db");
console.debug("Serving request xxxxxxx");

[samshdn]

I agree with what you said.
Your ExternalError is equivalent to my BusinessError, and your InternalError is equivalent to my SystemError, these are exceptions. Normally, we log the InternalError/exception but do not send exception details back to the user.

The reason for defining two types of Error classes is as follows:

• We want to centralize error handling for both ExternalError/BusinessError and InternalError/SystemError.
• We need to distinguish the error type within the error handling context.

[jduan00]

How about: UserErrors and SystemErrors?

[samshdn]

Both names, UserError and SystemError, are fine.

If UserErrors or SystemErrors are used, they are likely to be registries for storing multiple entries.

pseudo code

class UserError extends Error {
  code: string;
  constructor(code: string,message: string) {
    super(message);
    this.code = code;
  }
}

class SystemError extends Error {
  constructor(message: string) {
    super(message);
    this.code = 500;
  }
}

[jduan00]

Builtin debugging for deno:

https://deno.com/blog/zero-config-debugging-deno-opentelemetry

Fly.io logging

https://fly.io/docs/monitoring/logging-overview/