In partnership with

Hello “👋

Welcome to another week, another opportunity to become a Great Backend Engineer.

Today’s issue is brought to you by Masteringbackend → A great resource for backend engineers. We offer next-level backend engineering training and exclusive resources.

Before we get started, I have a few announcements:

I have a special gift for you: You will love this one.

The ultimate “Land Your Dream Job” Challenge is here.

We are launching the ultimate guide to land your dream job in any programming language you choose. We are starting with the Python Programming language.

Land your dream Python Job in 90 days by shipping 30 Python projects in 30 days by completing our daily tasks.

It’s a cohort-based and project-focused challenge where you will be challenged to build 30 Python projects in 30 days.

Here is what you will get:

• Ship 30+ Python backend projects in 30 days.

• Instant Access to all 30+ videos

• Access to data structure and algorithm interview kits.

• Access our Complete Backend Job Preparation kits (Resume, Cover letter reviews, mock interviews, and job placements).

• Join & learn from a thriving community of helpful students & alumni from top companies.

Limited Access. The first 500 students will be at $54, others at $100 (We have only 220 slots left.)

Click here to reserve your spot.

Start learning AI in 2025

Everyone talks about AI, but no one has the time to learn it. So, we found the easiest way to learn AI in as little time as possible: The Rundown AI.

It's a free AI newsletter that keeps you up-to-date on the latest AI news, and teaches you how to apply it in just 5 minutes a day.

Plus, complete the quiz after signing up and they’ll recommend the best AI tools, guides, and courses – tailored to your needs.

Sign up to start learning.

In our previous issue on HATEOAS in API Design, we explored HATEOAS as a key concept in designing RESTful APIs (Application Programming Interfaces), which implies that the API delivers data and information about available interactions.

In this issue, we'll explore best practices for API error handling, structure error responses, and implement a robust error-handling system in a RESTful API using Node.js and Express.

Introduction

Error handling is a critical aspect of API design that directly impacts an API's usability, reliability, and stability. When APIs fail to handle errors properly, consumers experience unexpected failures, making debugging and maintenance more challenging.

A well-structured error-handling mechanism ensures that issues are properly captured, categorized, and communicated to users, allowing them to respond effectively.

Principles of Effective Error Handling

Use Standard HTTP Status Codes

HTTP status codes provide a universal language for conveying success or failure responses. Some key categories include:

• 2xx (Success): Indicates a successful request (e.g., 200 OK, 201 Created).

• 4xx (Client Errors): Indicates issues with the client request (e.g., 400 Bad Request, 401 Unauthorized, 404 Not Found).

• 5xx (Server Errors): Indicates issues with the API server (e.g., 500 Internal Server Error, 503 Service Unavailable).

Provide Meaningful Error Messages

Error messages should be clear, concise, and actionable. Avoid exposing sensitive internal information; provide details that help clients resolve the issue.

Bad Example:

{
  "error": "Something went wrong."
}

Good Example:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The 'email' field is required.",
    "details": [
      {
        "field": "email",
        "issue": "Missing required field."
      }
    ]
  }
}

Maintain a Consistent Error Response Format

APIs should return errors in a consistent structure to help developers anticipate and handle them easily.

A standard error response format might include:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found.",
    "details": []
  }
}

Log Errors for Debugging

Logging errors helps diagnose issues and improve API reliability. To aid troubleshooting, logs should include error details, timestamps, and request context.

Avoid Overexposing Internal Errors

APIs should not reveal sensitive information like stack traces, database errors, or internal implementation details to clients. Instead, they should provide generic error messages and log detailed errors internally.

Implementing Error Handling in Node.js (Express)

Let's implement a structured error-handling system in a Node.js Express API.

Define a Custom Error Class

class ApiError extends Error {
  constructor(statusCode, message, details = []) {
    super(message);
    this.statusCode = statusCode;
    this.details = details;
  }
}

Create a Centralized Error Handling Middleware

const errorHandler = (err, req, res, next) => {
  const statusCode = err.statusCode || 500;
  const response = {
    error: {
      code: err.code || "INTERNAL_SERVER_ERROR",
      message: err.message || "An unexpected error occurred.",
      details: err.details || []
    }
  };
  
  console.error("API Error:", response); // Log error details
  res.status(statusCode).json(response);
};

module.exports = errorHandler;

Use the Middleware in an Express App

const express = require("express");
const app = express();
const errorHandler = require("./middlewares/errorHandler");

app.use(express.json());

// Example Route with Error Handling
app.get("/user/:id", async (req, res, next) => {
  try {
    const userId = req.params.id;
    if (!userId) {
      throw new ApiError(400, "User ID is required.", [{ field: "id", issue: "Missing parameter" }]);
    }
    // Simulate fetching user (Assume user doesn't exist)
    throw new ApiError(404, "User not found.");
  } catch (error) {
    next(error);
  }
});

// Apply the global error handler
app.use(errorHandler);

app.listen(3000, () => {
  console.log("Server running on port 3000");
});

Handling Different Error Scenarios

Now, let’s explore some types of errors and a proper way to send the response to your client.

Validation Errors

If the request payload is invalid, return 400 Bad Request with details.

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Username is required.",
    "details": [{ "field": "username", "issue": "Missing parameter" }]
  }
}

Authentication & Authorization Errors

Unauthorized access attempts should return 401 Unauthorized or 403 Forbidden.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key. Access denied."
  }
}

Resource Not Found

When a requested resource doesn’t exist, return 404 Not Found.

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested user was not found."
  }
}

Internal Server Errors

For unexpected server-side issues, return 500 Internal Server Error with a generic message.

{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred. Please try again later."
  }
}

A well-defined error-handling strategy is essential for building robust and user-friendly APIs. By using standard HTTP status codes, providing meaningful error messages, maintaining a consistent response structure, and implementing centralized error handling in Node.js, you can significantly enhance the API's reliability and developer experience.

Following these best practices ensures that your API remains resilient, predictable, and easy to debug, ultimately improving the overall stability of your system.

Did you learn any new things from this newsletter this week? Please reply to this email and let me know. Feedback like this encourages me to keep going.

Remember to start learning backend engineering from our courses:

Get a 50% discount on any of these courses. Reach out to me (Reply to this mail)

1. Become a Node.js Backend Engineer is Live

2. Become a Rust Backend Engineer is Live

3. Become a Python Backend Engineer is Live

4. Become a Java + Spring Backend Engineer is Live

Backend Engineering Resources

1. Backend Engineering Hub

2. All Backend Books

3. Visit our Backend Store

4. Join our Community

5. Backend Engineering Courses

LAST WORD 👋 

How am I doing?

I love hearing from readers, and I'm always looking for feedback. How am I doing with The Backend Weekly? Is there anything you'd like to see more or less of? Which aspects of the newsletter do you enjoy the most?

Hit reply and say hello - I'd love to hear from you!

Stay awesome,
Solomon

I moved my newsletter from Substack to Beehiiv, and it's been an amazing journey. Start yours here.