Why structured errors improve API quality in NestJS - See It in Action

Why structured errors improve API quality

📖 Scenario: You are building a simple NestJS API that returns user data. You want to improve the API quality by sending structured error responses when something goes wrong.

🎯 Goal: Create a NestJS controller that returns user data. Add structured error handling so the API returns clear, consistent error messages with status codes and error details.

📋 What You'll Learn

Create a users array with exact user objects

Add a variable to hold the user ID to find

Use a method to find the user by ID and throw a structured error if not found

Add a controller method that returns the user or the structured error response

💡 Why This Matters

🌍 Real World

APIs often need to tell clients exactly what went wrong. Structured errors make this clear and easy to handle.

💼 Career

Backend developers use structured error handling to build reliable, user-friendly APIs that frontend and mobile apps depend on.

1

Create the users data array

Create a constant array called users with these exact objects: { id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }, and { id: 3, name: 'Charlie' }.

NestJS

// Create the users array with exact user objects
// Your code here

Hint

Use const users = [ ... ] with the exact objects inside.

2

Add a variable for the user ID to find

Create a constant called userId and set it to 4 to simulate looking for a user that does not exist.

NestJS

const users = [
  { id: 1, name: 'Alice' },
  { id: 2, name: 'Bob' },
  { id: 3, name: 'Charlie' }
];

// Create userId variable set to 4
// Your code here

Hint

Use const userId = 4; exactly.

3

Find user by ID and throw structured error if not found

Create a function called findUserById that takes id as a parameter. Inside, find the user in users with matching id. If no user is found, throw a HttpException with status 404 and a JSON object containing statusCode, error, and message fields.

NestJS

const users = [
  { id: 1, name: 'Alice' },
  { id: 2, name: 'Bob' },
  { id: 3, name: 'Charlie' }
];

const userId = 4;

// Create findUserById function with structured error throw
// Your code here

Hint

Use HttpException from @nestjs/common to throw a structured error with status 404.

4

Add controller method to return user or structured error

Create a NestJS controller class called UserController with a method getUser that calls findUserById(userId) inside a try-catch block. Return the user if found. If an error is caught, rethrow it to send the structured error response.

NestJS

import { HttpException, HttpStatus } from '@nestjs/common';

const users = [
  { id: 1, name: 'Alice' },
  { id: 2, name: 'Bob' },
  { id: 3, name: 'Charlie' }
];

const userId = 4;

function findUserById(id: number) {
  const user = users.find(user => user.id === id);
  if (!user) {
    throw new HttpException({
      statusCode: 404,
      error: 'Not Found',
      message: `User with id ${id} not found`
    }, HttpStatus.NOT_FOUND);
  }
  return user;
}

// Create UserController class with getUser method using try-catch
// Your code here

Hint

Use @Controller and @Get decorators from @nestjs/common. Use try-catch to handle errors.

Practice

1. Why is it important to use structured errors in a NestJS API?

easy

A. They provide consistent and clear error messages for clients.

B. They make the API run faster by skipping error checks.

C. They hide error details to prevent debugging.

D. They automatically fix bugs in the code.

Solution

1. Step 1: Understand the role of structured errors

   Structured errors give clear, consistent feedback about what went wrong in the API.

2. Step 2: Identify the benefit for clients

   Clients get meaningful messages that help them understand and fix issues faster.

3. Final Answer:

   They provide consistent and clear error messages for clients. -> Option A

4. Quick Check:

   Clear error messages = A [OK]

Hint: Structured errors give clear feedback, not speed or auto-fixes [OK]

Common Mistakes:

• Thinking errors speed up the API
• Believing errors hide details always
• Assuming errors fix bugs automatically

2. Which of the following is the correct way to throw a structured HTTP error in NestJS?

easy

A. throw new HttpException({ message: 'Error occurred', status: 400 }, 400);

B. throw HttpException('Error occurred', 400);

C. throw new HttpException('Error occurred', 400);

D. throw new Error('HttpException', 400);

Solution

1. Step 1: Recall NestJS HttpException syntax

   HttpException constructor accepts a response object and a status code.

2. Step 2: Identify the correct structured error format

   Passing an object with message and status as the first argument is the proper way.

3. Final Answer:

   throw new HttpException({ message: 'Error occurred', status: 400 }, 400); -> Option A

4. Quick Check:

   HttpException with object and status = A [OK]

Hint: Use new HttpException({message, status}, code) syntax [OK]

Common Mistakes:

• Omitting 'new' keyword
• Passing string only without object
• Using generic Error instead of HttpException

3. Given this NestJS controller snippet, what will the client receive when getUser is called with an invalid ID?

import { Controller, Get, Param, HttpException, HttpStatus } from '@nestjs/common';

@Controller('users')
export class UserController {
  @Get(':id')
  getUser(@Param('id') id: string) {
    if (id !== '123') {
      throw new HttpException({ error: 'User not found', code: 'USER_404' }, HttpStatus.NOT_FOUND);
    }
    return { id, name: 'Alice' };
  }
}

medium

A. "User not found" string with 404 status

B. { "error": "User not found", "code": "USER_404" } with 404 status

C. { "message": "User not found" } with 200 status

D. Empty response with 404 status

Solution

1. Step 1: Analyze the error thrown for invalid ID

   The code throws HttpException with an object containing error and code, and status 404.

2. Step 2: Understand the client response

   The client receives the JSON object with error details and HTTP 404 status.

3. Final Answer:

   { "error": "User not found", "code": "USER_404" } with 404 status -> Option B

4. Quick Check:

   Structured error object with 404 = B [OK]

Hint: HttpException sends object and status as response [OK]

Common Mistakes:

• Expecting plain string instead of object
• Assuming 200 status on error
• Missing error code in response

4. Identify the problem in this NestJS error handling code:

throw new HttpException('Invalid input', 400);

Why might this be less helpful for API clients?

medium

A. It should use a custom error class instead of HttpException.

B. It uses the wrong status code for invalid input.

C. It does not log the error to the console.

D. It throws a string instead of a structured object, limiting error details.

Solution

1. Step 1: Examine the error thrown

   The error is a simple string message without structure.

2. Step 2: Understand impact on API clients

   Clients get only a string, missing extra info like error codes or fields.

3. Final Answer:

   It throws a string instead of a structured object, limiting error details. -> Option D

4. Quick Check:

   String error limits details = C [OK]

Hint: Use objects for detailed errors, not plain strings [OK]

Common Mistakes:

• Confusing status code correctness
• Thinking custom classes are mandatory
• Ignoring logging importance here

5. You want to improve your NestJS API error responses by adding a timestamp and a unique error ID to every error. Which approach best uses structured errors to achieve this?

hard

A. Use try-catch blocks to catch errors and ignore timestamp and errorId.

B. Add console.log statements with timestamp and errorId before throwing errors.

C. Extend HttpException to include timestamp and errorId in the response object.

D. Throw plain strings with timestamp and errorId concatenated.

Solution

1. Step 1: Understand how to add extra info to errors

   Extending HttpException allows customizing the error response object with extra fields.

2. Step 2: Evaluate options for structured error enhancement

   Adding timestamp and errorId inside the error object keeps responses consistent and useful for clients.

3. Final Answer:

   Extend HttpException to include timestamp and errorId in the response object. -> Option C

4. Quick Check:

   Custom HttpException with extra fields = D [OK]

Hint: Customize HttpException to add fields, not just logs or strings [OK]

Common Mistakes:

• Thinking console logs affect API response
• Using plain strings loses structure
• Ignoring error details in catch blocks