Node.js Error Handling Best Practices for APIs and Background Jobs

Overview

If your backend has grown beyond a few routes and scripts, error handling is usually where inconsistencies start to show. One endpoint returns a neat JSON error, another leaks a stack trace, and a background worker quietly fails without enough context to debug it later. The result is slow incident response and code that becomes harder to trust over time.

The goal of this article is to give you a stable pattern for nodejs error handling best practices across two common backend surfaces:

• APIs, where the client needs a clear and safe response.
• Background jobs, where the system needs retries, logging, and recovery behavior.

A useful mental model is to treat errors as part of your application design rather than as an afterthought. In practice, that means answering a few questions consistently:

• Is this an expected operational error or a programming bug?
• What should the caller or job runner see?
• What should be logged for debugging?
• Should the process continue, retry, or stop?

For API work, this fits well alongside a resource-oriented design approach. If you are refining your routes and response shapes, pair this guide with REST API Design Best Practices Checklist for New Projects.

At a high level, the most reliable approach looks like this:

1. Create application-specific error classes.
2. Normalize unknown errors at your boundaries.
3. Return a consistent error response format.
4. Log structured context, not just messages.
5. Handle async errors explicitly.
6. Separate API error behavior from background job behavior.
7. Crash intentionally on truly unrecoverable process-level failures.

This is the core of practical javascript backend error handling: your system should fail in ways that are understandable, observable, and safe.

Template structure

Here is a reusable structure you can apply across projects. The exact libraries may change, but the pattern stays useful.

1. Define a base application error

Start with a small custom error class that captures the fields your app needs. For APIs, that usually includes an HTTP status code and a public message. For jobs, it may also include retry hints or an error code.

class AppError extends Error {
  constructor(message, options = {}) {
    super(message);
    this.name = this.constructor.name;
    this.statusCode = options.statusCode || 500;
    this.code = options.code || 'INTERNAL_ERROR';
    this.expose = options.expose || false;
    this.details = options.details;
    this.retryable = options.retryable || false;
    Error.captureStackTrace?.(this, this.constructor);
  }
}

class ValidationError extends AppError {
  constructor(message, details) {
    super(message, {
      statusCode: 400,
      code: 'VALIDATION_ERROR',
      expose: true,
      details
    });
  }
}

class NotFoundError extends AppError {
  constructor(message = 'Resource not found') {
    super(message, {
      statusCode: 404,
      code: 'NOT_FOUND',
      expose: true
    });
  }
}

class AuthError extends AppError {
  constructor(message = 'Unauthorized') {
    super(message, {
      statusCode: 401,
      code: 'UNAUTHORIZED',
      expose: true
    });
  }
}

This structure avoids scattering status codes and ad hoc messages around your codebase. It also gives you one place to evolve your conventions later.

2. Throw meaningful errors near the source

Do not wait until your global error middleware to figure out what went wrong. Convert low-level failures into domain-relevant errors as close to the source as practical.

async function getUserProfile(userId) {
  if (!userId) {
    throw new ValidationError('userId is required');
  }

  const user = await db.users.findById(userId);
  if (!user) {
    throw new NotFoundError('User not found');
  }

  return user;
}

This is cleaner than returning null in some places, booleans in others, and exceptions elsewhere. Pick one error contract and keep it consistent.

3. Add an async wrapper for route handlers

One of the most common sources of messy node api error handling is unhandled async logic in routes. A wrapper keeps route files readable.

const asyncHandler = (fn) => (req, res, next) => {
  Promise.resolve(fn(req, res, next)).catch(next);
};

Then use it like this:

app.get('/users/:id', asyncHandler(async (req, res) => {
  const user = await getUserProfile(req.params.id);
  res.json({ data: user });
}));

If you want a broader refresher on async flow, see How to Use Fetch API with Async Await: Common Patterns and Error Handling. The front-end examples are different, but the discipline around promise handling is the same.

4. Centralize API error middleware

Your global error middleware should convert any thrown value into a safe, consistent response shape.

app.use((err, req, res, next) => {
  const error = normalizeError(err);

  logger.error({
    message: error.message,
    code: error.code,
    statusCode: error.statusCode,
    path: req.path,
    method: req.method,
    requestId: req.id,
    stack: error.stack,
    details: error.details
  });

  res.status(error.statusCode).json({
    error: {
      code: error.code,
      message: error.expose ? error.message : 'Internal server error',
      details: error.expose ? error.details : undefined,
      requestId: req.id
    }
  });
});

And a normalizer:

function normalizeError(err) {
  if (err instanceof AppError) return err;

  return new AppError('Internal server error', {
    statusCode: 500,
    code: 'INTERNAL_ERROR',
    expose: false
  });
}

Two details matter here:

• Clients get safe output. Internal stack traces and raw database errors stay out of responses.
• Logs keep technical detail. Developers still have enough context to investigate.

5. Treat background jobs differently from request-response code

Background workers need a separate strategy because there is no client waiting for a JSON response. Instead, you care about retries, dead-letter handling, idempotency, and alerting.

async function processEmailJob(job) {
  try {
    await emailService.send(job.data);
    logger.info({ jobId: job.id, type: 'email', status: 'completed' });
  } catch (err) {
    const error = normalizeJobError(err);

    logger.error({
      jobId: job.id,
      queue: job.queueName,
      attempt: job.attemptsMade,
      retryable: error.retryable,
      code: error.code,
      message: error.message,
      stack: error.stack
    });

    if (error.retryable) {
      throw error;
    }

    await moveToDeadLetterQueue(job, error);
  }
}

This is a key distinction in node background job errors: not every failure should be retried, and not every non-retryable failure should crash the worker process.

6. Handle process-level errors intentionally

Unhandled promise rejections and uncaught exceptions should never be ignored. In many teams, the safest pattern is to log them, begin a graceful shutdown, and let your process manager restart the service.

process.on('uncaughtException', (err) => {
  logger.fatal({ err }, 'Uncaught exception');
  shutdownGracefully(1);
});

process.on('unhandledRejection', (reason) => {
  logger.fatal({ reason }, 'Unhandled rejection');
  shutdownGracefully(1);
});

The exact shutdown policy depends on your runtime and deployment setup, but the broader rule is simple: a process in an unknown state should not keep serving traffic as if nothing happened.

How to customize

The template above works best when you adapt it to the shape of your application rather than copying it line for line.

Define your error categories

Most backend applications benefit from a short list of standard categories:

• Validation errors: bad input, missing fields, malformed payloads.
• Authentication and authorization errors: invalid tokens, missing permissions.
• Not found errors: records or resources do not exist.
• Conflict errors: duplicate state, optimistic locking failures.
• Dependency errors: database, cache, third-party API, queue broker.
• Rate limit or quota errors: too many requests or job throughput limits.

For auth-related work, if your project deals with token debugging and validation, JWT Decoder Guide: How to Read, Validate, and Troubleshoot Tokens Safely is a useful companion reference.

Use stable error codes

Human-readable messages can change. Error codes should be more stable. A client can rely on VALIDATION_ERROR or UNAUTHORIZED even if the displayed message evolves.

This matters especially in APIs consumed by front-end applications or other services. Stable codes make UI states, retries, and analytics easier to maintain.

Add request and job context

An error message without context often slows debugging more than it helps. Include:

• Request ID or trace ID
• User ID, if available and safe to log
• Route or handler name
• Job ID and queue name
• Attempt count for retries
• Relevant dependency names, such as database or provider

Be careful not to log secrets, full tokens, passwords, or sensitive personal data. Good logging is specific, but not careless.

Decide what is retryable

For background jobs, define retryability with intention. A timeout from an external API may be retryable. A schema validation failure on the job payload usually is not. If you blur that line, your queue can fill with repeated failures that will never succeed.

A simple rule of thumb:

• Retryable: network timeouts, transient upstream failures, temporary rate limits.
• Non-retryable: invalid payloads, missing required configuration, permanent business rule violations.

Prefer structured logs over string-only logs

Logs like "payment failed" are hard to search and aggregate. Prefer object-based logging with keys such as code, paymentId, provider, and requestId. Even if your current setup is simple, structured logs age better as systems grow.

Type your errors if you use TypeScript

In mixed JavaScript and TypeScript codebases, typed error classes can reduce confusion around available fields. If your team is moving in that direction, see TypeScript for JavaScript Developers: A Practical Migration Guide. You do not need TypeScript for solid error handling, but it helps make conventions explicit.

Write small helper utilities

A few helpers go a long way:

• assertPresent(value, message)
• normalizeError(err)
• isRetryable(err)
• toPublicErrorResponse(err, requestId)

These utilities reduce repetition and make your project easier to standardize across routes, services, and workers.

If you are building out your broader backend skill set, Backend Developer Roadmap: Skills, Projects, and Tools to Learn is a helpful next read.

Examples

Below are a few practical examples of how these patterns play out in common Node.js scenarios.

Example 1: Validation failure in an API route

app.post('/posts', asyncHandler(async (req, res) => {
  const { title } = req.body;

  if (!title || title.trim().length < 3) {
    throw new ValidationError('Title must be at least 3 characters', {
      field: 'title'
    });
  }

  const post = await createPost(req.body);
  res.status(201).json({ data: post });
}));

The client gets a 400-level error with a useful message. Your logs still contain the request context. This is expected application behavior, not a server fault.

Example 2: Database dependency failure

async function loadAccount(id) {
  try {
    return await db.accounts.findById(id);
  } catch (err) {
    throw new AppError('Database operation failed', {
      statusCode: 503,
      code: 'DB_UNAVAILABLE',
      expose: false,
      retryable: true
    });
  }
}

Here the public message should stay generic. The raw database details belong in logs, not in API output.

Example 3: Background job with selective retry

async function processImportJob(job) {
  try {
    validateImportPayload(job.data);
    await importService.run(job.data);
  } catch (err) {
    if (err instanceof ValidationError) {
      logger.warn({ jobId: job.id, err }, 'Invalid import job payload');
      await markJobFailed(job.id, 'invalid_payload');
      return;
    }

    logger.error({ jobId: job.id, err }, 'Import job failed');
    throw new AppError('Import job failed', {
      code: 'IMPORT_FAILED',
      retryable: true
    });
  }
}

This avoids pointless retries for bad input while still allowing retries for transient operational failures.

Example 4: Express 404 fallback

app.use((req, res, next) => {
  next(new NotFoundError(`Route ${req.method} ${req.originalUrl} not found`));
});

This keeps unknown routes aligned with the rest of your response format instead of returning an unrelated default message.

Example 5: Service boundary normalization

Suppose a payment provider throws several different errors. Rather than exposing provider-specific behavior everywhere, map them into your own internal model:

function mapPaymentError(err) {
  if (err.code === 'RATE_LIMIT') {
    return new AppError('Payment provider temporarily unavailable', {
      statusCode: 503,
      code: 'PAYMENT_TEMPORARY_FAILURE',
      retryable: true,
      expose: false
    });
  }

  if (err.code === 'CARD_DECLINED') {
    return new AppError('Payment method was declined', {
      statusCode: 402,
      code: 'PAYMENT_DECLINED',
      expose: true
    });
  }

  return new AppError('Payment processing failed', {
    statusCode: 502,
    code: 'PAYMENT_ERROR',
    expose: false
  });
}

This kind of mapping is one of the most useful habits in an express error handling guide because it protects the rest of your app from low-level inconsistency.

As your codebase grows, these conventions also help in interviews and code reviews because they show a clear operational mindset. For related fundamentals, JavaScript Interview Questions by Topic: Arrays, Closures, Async, and DOM is worth bookmarking.

When to update

The best error handling system is not the one with the most abstractions. It is the one your team still understands and uses consistently six months later. That is why this topic should be revisited whenever the underlying inputs change.

Review your approach when any of the following happens:

• You add a new framework or runtime layer, such as a queue system, GraphQL server, or serverless handlers.
• You introduce observability tooling, including structured logging, tracing, or centralized error reporting.
• Your API response conventions change, especially if multiple clients depend on stable error codes.
• Your deployment model changes, which can affect shutdown behavior and process-level failure handling.
• Your retry strategy changes for scheduled tasks, imports, emails, or event processing.
• You start seeing repeated production incidents with missing context, unclear ownership, or noisy logs.

A practical maintenance checklist looks like this:

1. Audit your top five error types in logs.
2. Check whether each one has a clear code, message, and owner.
3. Verify that API responses do not leak internals.
4. Verify that background jobs distinguish retryable and non-retryable failures.
5. Confirm that uncaught exceptions trigger a documented shutdown path.
6. Update your examples and starter templates so new code follows the same pattern.

If you maintain internal docs or starter repositories, this is where a short “error handling contract” pays off. New contributors should be able to answer these questions quickly:

• Which error class should I throw here?
• What will the client receive?
• What gets logged?
• Will this retry if it fails in a worker?

For teams that revisit tooling regularly, it also helps to keep a small set of everyday utilities handy. The roundup at Best Free Developer Tools Online for Everyday Coding Tasks is a useful bookmark for that broader workflow.

To put this guide into action, start small: define one base error class, create one normalizer, standardize one API response shape, and add one logging convention for request and job context. You do not need a large framework to get the benefits. You need a system simple enough that your team will actually keep using it.