Centralizing Error Responses

Welcome back! In the last lesson, you learned how to validate incoming data to make sure your API only accepts correct and safe information. Now, let’s talk about what happens when something goes wrong — such as when a user sends bad data or tries to access something that doesn’t exist.

When building APIs, it’s important to provide clear and consistent error messages. If every part of your code handles errors differently, it can be confusing for both you and anyone using your API. Centralizing error responses means you have one place to control how errors are shown, making your code easier to read, maintain, and debug.

In this lesson, you’ll learn how to create a utility function to handle errors in a single, standard way. This will help you keep your API responses clean and predictable.

Before we dive in, let’s quickly remind ourselves of the basic setup we’ve been working with. Here’s a simple example of an API route and a user dataset, similar to what you’ve seen before:

// Example user dataset and basic API route
const users = [
  { id: 1, name: 'Alice', email: 'alice@example.com' },
  { id: 2, name: 'Bob', email: 'bob@example.com' }
];

export async function GET() {
  return new Response(JSON.stringify(users), { status: 200 });
}

This code defines a small list of users and a GET endpoint that returns all users as a JSON response. In previous lessons, you also learned how to validate incoming data when creating or updating users.

Let’s look at what happens if we handle errors directly in each route, without any standard approach. For example, you might see code like this:

export async function GET(req, { params }) {
  const id = parseInt(params.id);
  const user = users.find(u => u.id === id);
  if (!user) {
    return new Response(JSON.stringify({ error: 'User not found' }), { status: 404 });
  }
  return new Response(JSON.stringify(user), { status: 200 });
}

Now imagine you have many routes, and each one returns errors in a slightly different way. Some might use { error: '...' }, others might use { message: '...' }, and some might forget to include useful details like a timestamp or status code.

🧠 Why is this bad? Imagine building a frontend that has to interpret responses from 10 different routes — but one returns { message: 'not found' }, another { error: 'missing user' }, and another { detail: 'fail' }. You now have to check for every variation and hope the structure doesn’t change. This wastes time and breaks maintainability. This inconsistency can make it hard to understand what went wrong, both for you as the developer and for anyone using your API. It also makes your code harder to maintain, since you have to update error handling in many places if you want to make a change.

Instead, using one consistent format lets you write code once and reuse it everywhere. And that’s what centralization gives you.