error-handling

Error Handling

Error classification

• Programming errors: Bugs (TypeError, ReferenceError, assertion failures, etc.). Fix the code; do not catch and continue
• Operational errors: Expected failures (network timeout, file not found, invalid input, etc.). Handle gracefully with recovery, escalation, user notification, or logging

Sync error handling

try {
  const result = parse(input);
  return result;
} catch (error) {
  console.error({ error });
  return defaultValue;
}

Async error handling

try {
  const data = await fetchData(url);
  return data;
} catch (error) {
  if (error.code === 'ECONNREFUSED') return fallback();
  throw err;
}

DomainError

Structured business errors with codes for the API layer:

({
  method: async ({ email }) => {
    const user = await domain.user.findByEmail(email);
    if (!user) return new DomainError('ENOTFOUND');
    return user;
  },
  errors: { ENOTFOUND: 'User not found' },
});

Domain layer throws plain errors; API layer translates to DomainError when needed.

Error propagation across layers

domain throws Error → API catches → returns DomainError(code) → client gets structured error

Do not expose internal error details to clients; map to known error codes or general errors.

Conventions

• Distinguish programmer vs operational errors; only recover from operational
• Use DomainError for business validation in API methods; throw for programming bugs
• Never swallow errors silently; always log or propagate
• Implement graceful shutdown: stop accepting connections, drain existing, release resources
• Use retry with exponential backoff for transient failures (network, DB connections)
• Always handle both uncaughtException and unhandledRejection at process level

Retry pattern

const retry = async (fn, { attempts = 3, delay = 1000 } = {}) => {
  for (let i = 0; i < attempts; i++) {
    try {
      return await fn();
    } catch (err) {
      if (i === attempts - 1) throw err;
      await new Promise((r) => setTimeout(r, delay * (i + 1)));
    }
  }
};