DEV Community: Riyon Sebastian

How I Started Capturing What Actually Happens When an API Fails

Riyon Sebastian — Tue, 07 Apr 2026 15:51:03 +0000

Most monitoring tools tell you one thing

"Your API is down."

That's useful. But only partially.

I wanted to go beyond "it's down" and understand why — specifically, where in the request lifecycle things actually broke.

The frustrating part of debugging failures

The first time this really hit me, I spent almost an hour digging through logs after a 3am alert — only to realize the issue had already disappeared. No trace of what went wrong. Just a gap in the metrics and a resolved status.

The typical workflow looks like this:

You get an alert
You SSH into your server
You check logs
You try to reproduce the issue

And in many cases… the issue is already gone.

The failure might have lasted only a few seconds:

A DNS resolution issue
A TLS handshake problem
A temporary upstream timeout

By the time you investigate, there's no trace left.

Logs don't always tell the full story

Logs are helpful, but they have real limitations:

They only capture what your application explicitly logs
They often miss network-level issues entirely
They don't show how a request failed step by step

What I kept missing was the network-level picture — not what the app logged, but what actually happened between the client and the server at each phase of the request.

Breaking down an HTTP request

When you make a request to an API, a lot happens under the hood:

DNS lookup — translating the domain name into an IP address
TCP connection — establishing a connection to the server
TLS handshake — negotiating encryption (for HTTPS)
Server processing — the server does its work and prepares a response
First byte received — also called TTFB (Time To First Byte), this is the total time from sending the request to getting the first byte back. It's not a separate step — it's a cumulative measurement across all the steps above.

If any one of these steps fails or slows down, the entire request is affected.

Most monitoring tools treat the request as a single opaque event — you only see the result, not what happened during the request.

The idea: capture the failure at the moment it happens

Instead of trying to debug after the failure has resolved itself...

What if we could capture useful diagnostic signals during the failure?

So I started experimenting with capturing:

DNS lookup timing
TLS handshake duration
Time to first byte
The first part of the response body

At the exact moment a request fails.

I ended up building a small tool around this idea — I call it Pinghawk.

What this actually changes

To see why this matters, here's what a typical monitoring alert looks like:

ALERT: API DOWN
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
endpoint:  api.myapp.io/payments
status:    DOWN
started:   2026-03-26 09:05:25
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

That's everything you get. Now you start the investigation — SSH, logs, curl, check DNS, check TLS. By the time you look, the evidence is usually gone.

Now here's what it looks like when you capture diagnostic data at each failure. The tool waits for three consecutive failures before alerting (more on why below), and captures a snapshot at each one silently:

Example A — Server degradation into timeout

--- SNAPSHOT #1 ---                         ap-southeast-1
───────────────────────────────────────────────────────────
  dns_lookup       1ms                       (~estimated)
  tls_handshake    5ms                   (SSL negotiation)
  ttfb             4,007ms                     ↑ critical
                   server is very slow or overloaded
  total_time       4,312ms
───────────────────────────────────────────────────────────

--- SNAPSHOT #2 ---                         ap-southeast-1
───────────────────────────────────────────────────────────
  dns_lookup       2ms                       (~estimated)
  tls_handshake    4ms                   (SSL negotiation)
  ttfb             10,002ms                    ↑ critical
                   server is very slow or overloaded
  total_time       10,374ms                      ↑ worse
───────────────────────────────────────────────────────────

--- SNAPSHOT #3 ---                         ap-southeast-1
───────────────────────────────────────────────────────────
  error            TIMEOUT
                   Your server did not respond within
                   the allowed time. May be overloaded,
                   crashed, or unreachable.
  total_time       10,000ms
───────────────────────────────────────────────────────────

TTFB went from 4,007ms to 10,002ms to a full timeout. The server was degrading under load until it stopped responding entirely. You can see the failure developing across three snapshots.

Example B — Upstream dependency failure

--- SNAPSHOT #1 ---                         ap-southeast-1
───────────────────────────────────────────────────────────
  dns_lookup       3ms                       (~estimated)
  tls_handshake    12ms                  (SSL negotiation)
  ttfb             1,847ms                        ↑ high
  status_code      502
                   Bad Gateway — upstream service
                   returned an invalid response
  response_body    {"error":"upstream_timeout",
                    "service":"payment-gateway"}
───────────────────────────────────────────────────────────

--- SNAPSHOT #2 ---                         ap-southeast-1
───────────────────────────────────────────────────────────
  ttfb             1,923ms                        ↑ high
  status_code      502
  response_body    {"error":"upstream_timeout",
                    "service":"payment-gateway"}
───────────────────────────────────────────────────────────

--- SNAPSHOT #3 ---                         ap-southeast-1
───────────────────────────────────────────────────────────
  ttfb             2,104ms                        ↑ high
  status_code      502
  response_body    {"error":"upstream_timeout",
                    "service":"payment-gateway"}

  ┌─────────────────────────────────────────────────────┐
  │  DNS ✓  TLS ✓  Server responded — upstream failed.  │
  │  Payment gateway timed out. Your server is fine.     │
  └─────────────────────────────────────────────────────┘
───────────────────────────────────────────────────────────

DNS fine. TLS fine. Your server responded — but the payment gateway behind it timed out. No SSH session required.

The difference: instead of starting an investigation after the alert, the evidence is already there when the alert arrives.

The tricky part: getting this data in Node.js

This turned out to be harder than expected.

Most high-level APIs like fetch don't expose DNS timing or TLS handshake duration at all. They give you a response, but no visibility into the individual phases of how that response was obtained.

To get this data, I ended up using undici (the HTTP client that powers Node.js fetch under the hood) combined with Node.js diagnostics_channel. This lets you subscribe to events that fire at specific moments during a request:

import diagnostics_channel from 'node:diagnostics_channel'

let connectStartMs = null
let connectEndMs = null
let headersMs = null

diagnostics_channel.subscribe('undici:client:beforeConnect', () => {
  connectStartMs = Date.now()
})

diagnostics_channel.subscribe('undici:client:connected', () => {
  connectEndMs = Date.now()  // Real TCP + TLS handshake time
})

diagnostics_channel.subscribe('undici:request:headers', () => {
  headersMs = Date.now()  // Real TTFB
})

// After the request completes:
// connectEndMs - connectStartMs = real TCP + TLS handshake time
// headersMs - requestStartMs = real TTFB
// Remember to unsubscribe after the request completes

Here's what each metric actually gives you — and whether it's a real measurement or an estimate:

Metric	Source	Real or estimated?
connect_ms	`undici:client:connected`	Real
ttfb_ms	`undici:request:headers`	Real
total_ms	`Date.now()` delta	Real
tls_ms	~55% of connect_ms (HTTPS)	Estimated
tcp_ms	connect_ms - tls_ms	Estimated
dns_ms	~12% of connect_ms	Estimated

A few things worth noting honestly:

DNS timing is estimated, not exact. Node.js doesn't expose real DNS resolution timing through diagnostics_channel. The values I capture are close estimates based on the overall connect time — useful for spotting anomalies, but not precise measurements. That's why the examples above show (~estimated) next to DNS values.
The diagnostics_channel events are semi-internal. They work well today, but undici doesn't guarantee these channel names will stay stable across Node.js versions. It's a tradeoff — you get real timing data, but you're relying on an API that could change.
The capture is a separate request. When a check fails, the tool makes a second HTTP request using undici to capture the timing breakdown. This means the snapshot might not match the original failure exactly — the server could have recovered, or the error could be different. It's a real tradeoff I'm still thinking about. The alternative would be to instrument the original request, but that adds complexity to the main check path.

I wanted real timing data, even if it meant accepting these tradeoffs.

One more design decision: don't alert on the first failure

As you saw in the examples above, the tool waits for three consecutive failures before sending an alert — and captures a snapshot at each one silently:

Check 1 fails → snapshot #1 captured silently
Check 2 fails → snapshot #2 captured silently
Check 3 fails → snapshot #3 captured + alert sent with all three

Why three? It's enough to filter out transient blips (a single DNS hiccup, a momentary network glitch), but short enough to catch real outages within minutes at typical check intervals.

The result:

Fewer false alarms — transient issues don't wake you up at 3am
A progression timeline — you can see the failure developing across three snapshots (like the degradation in Example A above)
Evidence arrives with the alert — all three snapshots are attached before you even open it
Recovery is handled too — two consecutive successes resolve the incident and send a recovery notification with the total downtime duration

A small shift in thinking

What changed for me was this:

Don't just detect failures — capture context when they happen.

That one shift made debugging much faster and less frustrating. By the time the alert arrives, the evidence is already there.

Still exploring

There are still open questions here — especially around DNS timing accuracy and how closely the snapshot matches the original failure when it's captured as a separate request.

I'm curious how others handle this:

How do you usually debug short-lived or transient API failures?

Do you rely on logs, APM tools, distributed tracing, or something else entirely? Have you found a good way to capture context at the moment of failure rather than investigating after the fact?

Would love to hear what works for you.

Building a Robust Frontend Error-Handling System with Axios and Custom Hooks

Riyon Sebastian — Sat, 02 Nov 2024 09:52:27 +0000

Introduction

Effective error handling is crucial for providing a seamless user experience and maintaining clean, scalable code. In complex applications, managing errors manually across components often leads to cluttered and inconsistent code. This guide will show you how to build a modular, scalable, and centralized error-handling system in React using Axios, a custom hook (useApi), and modular service layers to create a user-friendly, organized, and efficient structure.

Note: This guide demonstrates a centralized, consistent structure for handling errors. While the approach offers a solid foundation for managing errors across an application, it’s essential to evaluate and adapt it based on specific production needs. Certain cases may benefit from context-specific handling (e.g., inline messages, modals) rather than relying solely on toast notifications. Use this structure as a starting point and customize it to fit the unique requirements of your application.

A Flexible Approach: There are many ways to handle errors in complex applications, and this is one of several effective approaches. I’ve chosen this method for its balance of modularity and scalability, which has proven beneficial across projects. I’ll walk you through the choices I made and why they work well for a variety of setups.

📚 Free Udemy Course (Structured Content)

Want a structured learning path to master error handling in React? Check out my free Udemy course:

Master React Error Handling with Axios and Hooks

✅ Why This Course?

Comprehensive, hands-on lessons.
Perfect for beginners and intermediate developers.
Absolutely free!

🎥 Watch the Full Tutorial on YouTube

Prefer a guided, step-by-step walkthrough? Watch my detailed YouTube tutorial:

Simplifying React Error Handling: Build a Robust Frontend System

In this video, I demonstrate:

Centralized Error Handling: Learn to manage API calls and errors systematically.
Clean, Scalable Code: Use React hooks and service modules for efficient error handling.
Real-World Applications: Create maintainable systems that fit projects of any size.

🛠️ Explore the Source Code on GitHub

Want to dive deeper into the implementation? Access the complete source code here:

Centralized Error Handling System for React

What’s Inside?

Fully functional code for the centralized error-handling system.
Step-by-step implementation aligned with the tutorial.
Ready to use in your own projects!

Hook: Why Centralized Error Handling Matters

Imagine you're building an e-commerce platform. Multiple components fetch data from various APIs, and each might fail for different reasons—network issues, server errors, or invalid user input. Without a centralized error-handling system, your code becomes cluttered with repetitive error checks, and users receive inconsistent feedback. How can you streamline this process to ensure reliability and a seamless user experience? This guide will show you how.

By the end, you’ll learn:

How to set up centralized error handling with Axios interceptors.
The role of a custom useApi hook for managing API request state.
The benefits of using service modules to organize API logic.
Advanced techniques for user-friendly error handling, including retry options and request cancellation.

Why Centralized Error Handling?
Basic Implementation
Setting Up the Axios Instance with Interceptors
Creating the Custom useApi Hook
Understanding Promises and Promise Rejection
Organizing Service Modules
Example: User Service
Advanced Enhancements (Optional)
- Error Parsing Customization
- Retry Mechanism
- Detailed Notifications
- Cancel Requests on Component Unmount
Connecting Dots
Visual Summary
Putting It All Together: A Real-World Example
Best Practices
Further Reading
Troubleshooting
Environment Configuration
Conclusion
Call to Action

Why Centralized Error Handling?

Centralized error handling addresses two common challenges:

Repetitive Error Code

Issue: Without a central mechanism, components rely on multiple try-catch blocks.
Impact: Leads to inconsistent error handling and redundant code.

Inconsistent User Experience

Issue: Error messages may vary across the app without centralization.
Impact: Creates a disjointed user experience and can confuse users.

Using a centralized approach with Axios interceptors, a custom hook (useApi), and service modules solves these issues by:

Single Location for Error Parsing and Messaging: Provides a unified place to handle all errors, ensuring consistency.
Separation of Concerns: Allows components to focus purely on data presentation and user interaction, leaving error handling to centralized modules.

Basic Implementation

Setting Up the Axios Instance with Interceptors

Axios interceptors are functions that Axios calls for every request or response. By setting up response interceptors, you can globally handle errors, parse responses, and perform actions like logging or redirecting users based on specific conditions.

Step 1: Import Necessary Modules

// utils/axiosInstance.js
import axios from 'axios';
import ERROR_MESSAGES from '../config/customErrors';
import { toast } from 'react-toastify';
import Router from 'next/router';

Step 2: Create the Axios Instance

const axiosInstance = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_BASE_URL || '',
  headers: {
    'Content-Type': 'application/json',
  },
});

Step 3: Add a Response Interceptor

axiosInstance.interceptors.response.use(
  (response) => response,
  (error) => {
    let message = ERROR_MESSAGES.GENERIC_ERROR;

    if (error.response) {
      const { status, data } = error.response;

      // Attempt to use a custom error message from the server
      if (data && data.message) {
        message = data.message;
      } else {
        // Fallback to predefined error messages
        message = ERROR_MESSAGES[status] || ERROR_MESSAGES.GENERIC_ERROR;
      }

      // Handle 401 Unauthorized
      if (status === 401) {
        Router.push('/login'); // Redirect to the login page
      }
    } else {
      // Handle network errors
      message = ERROR_MESSAGES.NETWORK_ERROR;
    }

    toast.error(message); // Display the error message
    return Promise.reject(new Error(message)); // Reject the promise with the error message
  }
);

Explanation:

Error Parsing: The interceptor checks if the error has a response. If not, it assumes a network error and displays a corresponding message.
Custom Error Messages: It attempts to use custom error messages based on the error type provided by the server. If none are available, it falls back to predefined messages.
User Feedback: Utilizes react-toastify to show toast notifications, enhancing user experience by providing immediate feedback.
Redirection: Redirects users to the login page if a 401 Unauthorized error occurs, ensuring security by preventing unauthorized access.

Step 4: Export the Axios Instance

export default axiosInstance;

Custom Error Messages

Define your custom error messages in a separate configuration file to maintain consistency and ease of management.

// config/customErrors.js

const ERROR_MESSAGES = {
  401: "You are not authorized to view this resource. Please log in.",
  403: "You do not have permission to perform this action.",
  500: "An unexpected server error occurred. Please try again later.",
  GENERIC_ERROR: "Something went wrong. Please try again.",
  NETWORK_ERROR:
    "Network error, unable to reach the server. Please check your connection.",
};

export default ERROR_MESSAGES;

Quick Summary: Axios Interceptor Configuration

Setting up Axios interceptors provides:

Centralized Error Parsing: Manages errors in one place, ensuring consistency across all API requests.
User Feedback: Utilizes react-toastify to notify users about issues immediately.
Redirection and Security: Redirects unauthorized users to login when needed, keeping the app secure.

This centralized Axios instance is key to building a reliable, user-friendly API communication layer that ensures consistent management of all API requests and error handling across your application.

Creating the Custom `useApi` Hook

The useApi hook centralizes API request handling, managing loading, data, and error states. By abstracting this process, useApi allows components to avoid repetitive try-catch blocks and focus on data presentation.

Parameters:

apiFunc (Function): The API function to execute, typically from service modules.
immediate (Boolean, optional): Determines whether the API call should be made immediately upon hook initialization. Defaults to false.

Returned Values:

data: The response data from the API call.
loading: Indicates whether the API call is in progress.
error: Captures any error messages from failed API calls.
request: The function to initiate the API call, which can be called with necessary parameters.

Implementation:

// hooks/useApi.js
import { useState, useCallback } from 'react';

const useApi = (apiFunc, immediate = false) => {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(immediate);
  const [error, setError] = useState(null);

  const request = useCallback(async (...args) => {
    setLoading(true);
    setError(null);
    try {
      const result = await apiFunc(...args);
      setData(result.data);
    } catch (err) {
      setError(err.message);
    } finally {
      setLoading(false);
    }
  }, [apiFunc]);

  return { data, loading, error, request };
};

export default useApi;

Explanation:

State Management:
- data: Stores the response data.
- loading: Indicates if the API call is in progress.
- error: Captures any error messages.
request Function:
- Initiates the API call.
- Manages state updates based on the API call's outcome.

Understanding Promises and Promise Rejection

Before diving deeper, it's essential to understand Promises and Promise Rejection in JavaScript, as they play a pivotal role in handling asynchronous operations like API calls.

Promises: A Promise is an object representing the eventual completion or failure of an asynchronous operation. It allows you to attach callbacks to handle the success (resolve) or failure (reject) of the operation.
Promise Rejection: When an operation fails, a Promise is "rejected," triggering the .catch method or the second parameter in .then.

Relevance in Axios and `useApi`:

Axios and Promises: Axios uses Promises to handle HTTP requests. When you make a request using Axios, it returns a Promise that resolves with the response data or rejects with an error.
Promise Rejection in Axios Interceptors: In the Axios interceptor, when an error occurs, the interceptor rejects the Promise using Promise.reject(error). This rejection propagates to where the API call was made.
Catching Rejections in useApi: The useApi hook's request function uses try-catch to handle these rejections. When apiFunc(...args) rejects, the catch block captures the error, updating the error state accordingly.

Importance of Handling Promise Rejections:

Prevent Unhandled Rejections: If Promise rejections aren't handled, they can lead to unexpected behaviors and make debugging difficult.
Consistent Error Management: By centralizing the handling of Promise rejections, you ensure that all errors are managed uniformly, enhancing code reliability and user experience.

What If `useApi` Hook Isn't Used?

Without the useApi hook, you would need to implement try-catch blocks in every component that makes an API call. This approach leads to:

Repetitive Code: Each component would have similar error-handling logic, increasing code redundancy.
Inconsistent Error Handling: Different components might handle errors differently, leading to an inconsistent user experience.
Increased Maintenance Effort: Updating error-handling logic would require changes across multiple components, making maintenance cumbersome.

By using the useApi hook, you abstract away the repetitive error-handling logic, promoting cleaner and more maintainable code.

Example Usage:

// src/components/ProductList.js
import React, { useEffect } from 'react';
import productService from '../services/productService';
import useApi from '../hooks/useApi';

const ProductList = () => {
  const { data, loading, error, request } = useApi(productService.getProducts, false);

  useEffect(() => {
    request({ page: 1, limit: 10 });
  }, [request]);

  if (loading) return <p>Loading products...</p>;
  if (error) return <p>Error: {error}</p>;

  return (
    <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
      {data?.data.map((product) => (
        <div key={product._id} className="border rounded p-4">
          <img src={product.images[0]} alt={product.name} className="w-full h-48 object-cover mb-4" />
          <h2 className="text-lg font-semibold">{product.name}</h2>
          <p className="text-gray-700">${product.price}</p>
        </div>
      ))}
    </div>
  );
};

export default ProductList;

In this example, the useApi hook manages the API call to fetch products. It handles loading states, captures any errors, and provides the fetched data to the component for rendering.

Organizing Service Modules

Service modules define API endpoint functions, organized by entity (e.g., users, products). This structure keeps API logic separate from component code, ensuring modularity and reuse.

Example: Product Service

// services/productService.js
import axiosInstance from "../utils/axiosInstance";

const getProducts = (params) => axiosInstance.get('/api/products', { params });
const getProductById = (id) => axiosInstance.get(`/api/products/${id}`);
const createProduct = (data) => axiosInstance.post('/api/products', data);

export default {
  getProducts,
  getProductById,
  createProduct,
};

Example: User Service

// services/userService.js
import axiosInstance from "../utils/axiosInstance";

const getUsers = (params) => axiosInstance.get('/api/users', { params });
const getUserById = (id) => axiosInstance.get(`/api/users/${id}`);
const createUser = (data) => axiosInstance.post('/api/users', data);

export default {
  getUsers,
  getUserById,
  createUser,
};

Benefits of Service Modules:

Enable Reuse and Modularity: API functions can be reused across multiple components, reducing code duplication.
Ensure Separation of Concerns: Keeps components clean by moving API logic into services, improving code organization and maintainability.
Easier Testing: Service modules can be independently tested, ensuring that API interactions work as expected before integrating them into components.

Advanced Enhancements (Optional)

For those ready to take their error-handling system further, consider implementing these advanced techniques:

Error Parsing Customization

Categorize errors (e.g., network vs. validation) and provide actionable messages to help users understand issues and possible solutions.

Implementation:

// utils/axiosInstance.js
import axios from 'axios';
import ERROR_MESSAGES from '../config/customErrors';
import { toast } from 'react-toastify';
import Router from 'next/router';

const axiosInstance = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_BASE_URL || '',
  headers: {
    'Content-Type': 'application/json',
  },
});

axiosInstance.interceptors.response.use(
  (response) => response,
  (error) => {
    if (!error.response) {
      toast.error(ERROR_MESSAGES.NETWORK_ERROR);
      return Promise.reject(new Error(ERROR_MESSAGES.NETWORK_ERROR));
    }

    const { status, data } = error.response;
    let message = ERROR_MESSAGES[status] || ERROR_MESSAGES.GENERIC_ERROR;

    // Custom logic for specific error types
    if (data?.type === 'validation') {
      message = `Validation Error: ${data.message}`;
    } else if (data?.type === 'authentication') {
      message = `Authentication Error: ${data.message}`;
    }

    toast.error(message);

    if (status === 401) {
      Router.push('/login');
    }

    return Promise.reject(new Error(message));
  }
);

export default axiosInstance;

Explanation:

Error Categorization: The interceptor checks the type property in the error response to determine the nature of the error (e.g., validation or authentication).
Actionable Messages: Provides users with specific error messages based on the error type, enhancing their understanding and ability to respond appropriately.

Retry Mechanism

Implement retry options for failed requests, such as a retry button in the UI or automatic retries with exponential backoff, to enhance reliability.

Implementation:

// utils/axiosInstance.js
import axios from 'axios';
import axiosRetry from 'axios-retry';
import ERROR_MESSAGES from '../config/customErrors';
import { toast } from 'react-toastify';
import Router from 'next/router';

const axiosInstance = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_BASE_URL || '',
  headers: {
    'Content-Type': 'application/json',
  },
});

// Configure axios-retry
axiosRetry(axiosInstance, {
  retries: 3, // Number of retry attempts
  retryDelay: (retryCount) => retryCount * 1000, // Exponential backoff
  retryCondition: (error) => {
    return axiosRetry.isNetworkOrIdempotentRequestError(error) || error.response.status === 500;
  },
  onRetry: (retryCount, error, requestConfig) => {
    console.log(`Retrying request to ${requestConfig.url} (${retryCount}/3)`);
  },
});

axiosInstance.interceptors.response.use(
  (response) => response,
  (error) => {
    if (!error.response) {
      toast.error(ERROR_MESSAGES.NETWORK_ERROR);
      return Promise.reject(new Error(ERROR_MESSAGES.NETWORK_ERROR));
    }

    const { status, data } = error.response;
    let message = ERROR_MESSAGES[status] || ERROR_MESSAGES.GENERIC_ERROR;

    // Custom logic for specific error types
    if (data?.type === 'validation') {
      message = `Validation Error: ${data.message}`;
    } else if (data?.type === 'authentication') {
      message = `Authentication Error: ${data.message}`;
    }

    toast.error(message);

    if (status === 401) {
      Router.push('/login');
    }

    return Promise.reject(new Error(message));
  }
);

export default axiosInstance;

Explanation:

Retries: Configures Axios to retry failed requests up to three times with an exponential backoff strategy.
Retry Conditions: Retries occur for network errors, idempotent requests, or when the server responds with a 500 Internal Server Error.
Logging Retries: Logs each retry attempt, which can be useful for debugging and monitoring.

Detailed Notifications

Differentiate notifications by severity (info, warning, error) to help users understand the importance of the error.

Implementation:

// utils/axiosInstance.js
import axios from 'axios';
import ERROR_MESSAGES from '../config/customErrors';
import { toast } from 'react-toastify';
import Router from 'next/router';

const axiosInstance = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_BASE_URL || '',
  headers: {
    'Content-Type': 'application/json',
  },
});

axiosInstance.interceptors.response.use(
  (response) => response,
  (error) => {
    if (!error.response) {
      toast.error(ERROR_MESSAGES.NETWORK_ERROR);
      return Promise.reject(new Error(ERROR_MESSAGES.NETWORK_ERROR));
    }

    const { status, data } = error.response;
    let message = ERROR_MESSAGES[status] || ERROR_MESSAGES.GENERIC_ERROR;
    let notificationType = 'error'; // Default notification type

    // Custom logic for specific error types
    if (data?.type === 'validation') {
      message = `Validation Error: ${data.message}`;
      notificationType = 'warning';
    } else if (data?.type === 'authentication') {
      message = `Authentication Error: ${data.message}`;
      notificationType = 'error';
    } else if (status === 404) {
      message = ERROR_MESSAGES.NOT_FOUND;
      notificationType = 'info';
    }

    // Display error notification with appropriate severity
    toast[notificationType](message);

    if (status === 401) {
      Router.push('/login');
    }

    return Promise.reject(new Error(message));
  }
);

export default axiosInstance;

Explanation:

Notification Types: Determines the type of toast notification (info, warning, error) based on the error category.
User Feedback: Provides users with context-specific feedback, helping them understand the severity and nature of the issue.

Cancel Requests on Component Unmount

Use Axios cancel tokens to prevent memory leaks by canceling ongoing requests if a component unmounts.

Implementation:

// hooks/useApi.js
import { useState, useEffect, useRef, useCallback } from 'react';
import axios from 'axios';

const useApi = (apiFunc, immediate = false) => {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(immediate);
  const [error, setError] = useState(null);
  const cancelTokenSource = useRef(null);

  const request = useCallback(async (...args) => {
    setLoading(true);
    setError(null);

    // Cancel any previous request
    if (cancelTokenSource.current) {
      cancelTokenSource.current.cancel('Operation canceled due to new request.');
    }

    cancelTokenSource.current = axios.CancelToken.source();

    try {
      const result = await apiFunc(...args, {
        cancelToken: cancelTokenSource.current.token,
      });
      setData(result.data);
    } catch (err) {
      if (axios.isCancel(err)) {
        console.log('Request canceled:', err.message);
      } else {
        setError(err.message);
      }
    } finally {
      setLoading(false);
    }
  }, [apiFunc]); // Dependency array ensures `request` only changes if `apiFunc` changes.

  // Cleanup on component unmount
  useEffect(() => {
    return () => {
      if (cancelTokenSource.current) {
        cancelTokenSource.current.cancel('Component unmounted.');
      }
    };
  }, []);

  return { data, loading, error, request };
};

export default useApi;

Explanation:

Cancel Tokens: Utilizes Axios cancel tokens to cancel ongoing API requests when a new request is made or when the component unmounts.
Prevent Memory Leaks: Ensures that no state updates occur on unmounted components, preventing potential memory leaks.
Logging Canceled Requests: Logs canceled requests for debugging purposes.

Advanced Enhancements Summary

Implementing these advanced techniques takes your error-handling system to the next level:

Error Parsing Customization: Delivers more specific error messages to users, helping them understand and address issues directly.
Retry Mechanism: Improves reliability by allowing requests to retry automatically or manually after certain errors.
Detailed Notifications: Differentiates between error types, showing notifications based on severity to better inform users.
Cancel Requests on Component Unmount: Prevents memory leaks and redundant requests, ensuring a stable and efficient app performance.

These enhancements are optional but highly valuable as they add depth, flexibility, and user-focused improvements to your app’s error-handling approach.

Connecting Dots

When a component initiates an API call through useApi, the following flow is triggered:

Components Use Service Modules:

Each service module (e.g., userService, productService) defines functions for specific API endpoints and uses the configured axiosInstance. Components interact only with these service functions.

`useApi` Triggers Axios via the Service Module:

Components pass a service function (e.g., productService.getProducts) to useApi. When request is called, useApi forwards the function to the service, which then makes the HTTP request through axiosInstance.

Custom Error Parsing in Axios Interceptors:

The interceptors in axiosInstance handle error logging, parse predefined custom error messages, and centralize error handling.

Structured Responses from `useApi`:

useApi returns structured states (data, loading, and error) to the component, allowing it to focus solely on presenting data and handling interactions.

Visual Summary

The following outline describes how each component in the error-handling system interacts within the application, from the initial API call to user feedback:

Component
- The component initiates API requests using the useApi hook, which abstracts away the complexities of managing API calls, error handling, and loading states.
useApi Hook
- useApi is a custom hook that receives the function for the API request (from the service module). It manages the request’s loading state, handles errors, and returns structured responses (data, loading, error) back to the component.
Service Module
- The service module defines specific functions for each API endpoint (e.g., getProducts, createProduct) and uses the centralized axiosInstance for all requests, ensuring consistency across the application.
Axios Instance
- The axiosInstance manages HTTP requests and responses, applying any custom configurations like base URLs and headers.
API Response
- The response from the API is processed through Axios interceptors, which handle errors globally. This includes parsing custom error messages and triggering user notifications.
Error Handling & User Notifications
- Interceptors display error messages to the user via react-toastify notifications, and they can manage additional actions, like redirecting users to the login page on authentication errors.

This flow enables centralized error management and consistent user feedback, allowing components to focus solely on presenting data without needing to handle repetitive error-checking logic.

Putting It All Together: A Real-World Example

ProductList Component

This example demonstrates the entire flow, from making an API call to displaying data, with centralized error handling and feedback.

// ProductList component
import React, { useEffect } from 'react';
import { toast } from 'react-toastify';
import productService from '../services/productService';
import useApi from '../hooks/useApi';

const ProductList = () => {
  // Initialize useApi with the getProducts service function
  const { data, loading, error, request } = useApi(productService.getProducts, false);

  // Trigger the API request when the component mounts
  useEffect(() => {
    request({ page: 1, limit: 10 });
  }, [request]);

  // Display error notification if an error occurs
  useEffect(() => {
    if (error) {
      toast.error(error);
    }
  }, [error]);

  // Show loading state
  if (loading) return <p>Loading products...</p>;

  // Render the list of products
  return (
    <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
      {data?.data.map((product) => (
        <div key={product._id} className="border rounded p-4">
          <img src={product.images[0]} alt={product.name} className="w-full h-48 object-cover mb-4" />
          <h2 className="text-lg font-semibold">{product.name}</h2>
          <p className="text-gray-700">${product.price}</p>
        </div>
      ))}
    </div>
  );
};

export default ProductList;

Component Breakdown:

Import Statements:
- react-toastify: Used for displaying toast notifications.
- productService: Contains API functions related to products.
- useApi: Custom hook for managing API calls.
Hook Initialization:
- Initializes the useApi hook with the getProducts function from productService. The false parameter indicates that the API call shouldn't happen immediately upon hook initialization.
API Call Trigger:
- Uses useEffect to call the request function when the component mounts, fetching the first page of products.
Error Handling:
- Another useEffect listens for changes in the error state. If an error occurs, it triggers a toast notification to inform the user.
Conditional Rendering:
- Loading State: Displays a loading message while the API call is in progress.
- Error State: Shows an error message if the API call fails.
- Data Rendering: Once data is successfully fetched, it renders a grid of products with their images, names, and prices.

This example demonstrates how centralized error handling simplifies component logic and ensures consistent user feedback.

Best Practices

Adhering to best practices ensures that your error-handling system is efficient, maintainable, and user-friendly.

Separation of Concerns

Description: Keep API logic separate from UI components by using service modules. This improves code organization and maintainability.
Example: Instead of making API calls directly within components, delegate them to service modules like productService.js.

Consistent Error Messaging

Description: Handle all errors uniformly to simplify debugging and provide a seamless user experience.
Example: Using predefined error messages in customErrors.js ensures that users receive consistent feedback regardless of where the error originates.

Avoid Repetitive Code

Description: Use centralized error handling and custom hooks to eliminate repetitive try-catch blocks across components.
Example: The useApi hook manages error states and notifications, allowing components to focus solely on rendering data.

Meaningful Error Messages

Description: Provide user-friendly, actionable error messages to improve understanding and reduce frustration.
Example: Instead of displaying generic messages like "Error occurred," use specific messages such as "Validation Error: Please enter a valid email address."

Handle Edge Cases

Description: Anticipate and manage unexpected scenarios, such as network failures or server errors, to prevent your application from crashing.
Example: The Axios interceptor handles network errors by displaying a "Network error" toast and preventing the application from breaking.

Secure Error Handling

Description: Avoid exposing sensitive information in error messages. Provide user-friendly messages while logging detailed errors securely on the server.
Example: Display generic error messages to users while sending detailed error logs to a logging service like Sentry for developers.

Troubleshooting

1. Toast Notifications Not Appearing

Cause: The <ToastContainer /> component from react-toastify might be missing in your application.
Solution: Ensure that <ToastContainer /> is included in your main application component, typically in pages/_app.js.

// pages/_app.js
import { ToastContainer } from 'react-toastify';
import 'react-toastify/dist/ReactToastify.css';

function MyApp({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <ToastContainer />
    </>
  );
}

export default MyApp;

2. API Requests Not Caught by Interceptors

Cause: Service modules might be importing the default Axios library instead of the centralized axiosInstance.
Solution: Ensure that all service modules import the centralized axiosInstance.

// Correct Import
import axiosInstance from '../utils/axiosInstance';

// Incorrect Import
import axios from 'axios';

3. Redirects Not Working on Specific Errors

Cause: The Router from next/router might not be correctly imported or used outside of React components.
Solution: Ensure that the Axios interceptor is used in a context where Router can perform redirects. Alternatively, handle redirects within the useApi hook or within components.

Environment Configuration

Managing different environments ensures that your application interacts with the correct API endpoints during development, testing, and production.

Step 1: Define Environment Variables

Create a .env.local file in your project's root directory and define your API base URL:

NEXT_PUBLIC_API_BASE_URL=https://api.yourdomain.com

Step 2: Access Environment Variables in Code

Ensure that your Axios instance uses the environment variable:

const axiosInstance = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_BASE_URL || '',
  headers: {
    'Content-Type': 'application/json',
  },
});

Best Practices:

Secure Sensitive Information: Never commit .env.local files or any sensitive environment variables to your version control system. Use .gitignore to exclude these files.
Consistent Naming Conventions: Use clear and consistent naming for environment variables, typically prefixed with NEXT_PUBLIC_ to indicate they are exposed to the frontend.
Separate Configuration for Each Environment: Maintain separate .env files for different environments (e.g., .env.development, .env.production) to manage configurations effectively.

Conclusion

By building a centralized error-handling system, you’ve set up a clean, modular, and user-friendly structure that improves both developer experience and user satisfaction. Whether you're just starting or looking to enhance your app’s error management, this approach provides a solid foundation that can grow with your application.

Encourage yourself to experiment with the features described here, starting with the basics and adding enhancements as you grow comfortable. A centralized approach to error handling is a valuable skill and practice that will pay off as your application scales.

Call to Action

Ready to enhance your React/Next.js applications with centralized error handling?

Implement the strategies outlined in this guide to experience cleaner code, consistent user notifications, and improved maintainability.

Share Your Feedback

Have questions, suggestions, or experiences to share? Engage with the community by leaving comments or reaching out on GitHub and Twitter.

Stay Tuned for More

I'm working on developing an npm package based on this centralized error-handling system. Stay tuned for updates, or suggest features that you'd find valuable!

Happy Coding! 🚀✨

Efficiently Manage Errors in Next.js with a Comprehensive Developer Solution

Riyon Sebastian — Thu, 31 Oct 2024 16:15:57 +0000

Introduction

I’m thrilled to introduce a new lightweight package aimed at simplifying error management in Next.js applications: nextjs-centralized-error-handler. As developers, we often encounter challenges with error handling, especially within frameworks like Next.js, where traditional methods can lead to repetitive code and overlooked scenarios.

Drawing inspiration from my experience with the Yii2 framework—where built-in error classes streamline error management without the need to hardcode status codes or messages—I recognized a similar need in the Node.js ecosystem. This realization prompted the development of custom error classes within this package, enhancing both consistency and usability.

Important Note: This package is currently in beta. As a newly released tool, your feedback is essential for identifying potential issues and improving its stability. I encourage you to try out the nextjs-centralized-error-handler package and share your insights, whether through bug reports or suggestions for improvement. Together, we can strengthen this package for the Next.js community.

Introduction
Quick Start
- Install the Package
- Wrap Your API Route Handler
- Customize Error Handling (Optional)
Why Use nextjs-centralized-error-handler with Next.js Middleware?
Comparison with Next.js 13 Middleware
- Next.js 13 Middleware Example
- Comparison with nextjs-centralized-error-handler
- Understanding Scope and Flexibility: Next.js Middleware vs. nextjs-centralized-error-handler
Examples
- Handling Different HTTP Methods
- Validating Request Parameters
- Handling Unauthorized Access
- Enforcing Payload Limits
- Customizing Error Responses (Advanced)
Integration with Logging Services
Community Feedback and Stability
Benefits at a Glance
Conclusion

Quick Start

Install the Package

npm install nextjs-centralized-error-handler
# or
yarn add nextjs-centralized-error-handler

Wrap Your API Route Handler

// pages/api/example.js

const { errorHandler, BadRequestError } = require('nextjs-centralized-error-handler');

const handler = async (req, res) => {
  if (!req.body.name) {
    throw new BadRequestError('Name is required.');
  }

  res.status(200).json({ message: 'Success' });
};

export default errorHandler(handler);

Customize Error Handling (Optional)

const handler = async (req, res) => {
  // Your logic here
};

const options = {
  logger: customLoggerFunction,
  defaultMessage: 'Something went wrong!',
  formatError: (error, req) => ({
    message: error.message,
    type: error.name,
    timestamp: new Date().toISOString(),
  }),
};

export default errorHandler(handler, options);

Why Use `nextjs-centralized-error-handler` with Next.js Middleware?

Next.js 13’s middleware offers powerful global interception capabilities, ideal for tasks like authentication and general request validation. However, nextjs-centralized-error-handler enhances error handling by providing fine-grained, route-level control and detailed responses that middleware alone does not cover. Here’s how this package complements and extends Next.js middleware:

Route-Specific Error Management: With nextjs-centralized-error-handler, each route can define its own contextual error handling, with tailored messages that match the route’s functionality. This modularity is essential for complex applications with varied error handling needs across different endpoints.
Custom Error Classes with Detailed Responses: The package introduces custom error classes (e.g., BadRequestError, UnauthorizedError) with structured, frontend-friendly JSON responses. These responses are enriched with metadata like status codes and error types, ensuring predictable and standardized error handling for backend and frontend teams.
Enhanced Security and Data Privacy: Only errors that are intentional instances of CustomError have their status codes and messages sent to the client. For unexpected errors, a generic error message is used, and sensitive details are kept server-side, minimizing information leakage.
Logging and Integration with Monitoring Tools: Supports integration with logging services (e.g., Sentry, Datadog), enabling detailed error tracking and debugging beyond what middleware alone can achieve.
Customizable and Extensible Error Handling: The CustomError class is fully extensible, allowing developers to define application-specific errors, creating flexible error-handling strategies as applications evolve.

By combining Next.js middleware with nextjs-centralized-error-handler, you achieve a robust and flexible error-handling solution that supports both global and route-specific needs.

Comparison with Next.js 13 Middleware

Next.js 13 introduces global middleware, enabling request-level interception for tasks such as authentication and general validation. Below is a comparison showing how Next.js 13 middleware differs from nextjs-centralized-error-handler and when to use each.

Next.js 13 Middleware Example

Next.js 13 middleware can be defined globally and applied across all routes that match a specified pattern. This is useful for high-level operations like logging or authorization.

// middleware.js (placed at the root of the app)

import { NextResponse } from 'next/server';

export function middleware(req) {
  // Example of request validation or general logging
  if (!req.headers.get('Authorization')) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  return NextResponse.next(); // Continue to the route handler
}

// Optional: Configure route matching
export const config = {
  matcher: '/api/:path*', // Applies middleware only to /api/* routes
};

Comparison with nextjs-centralized-error-handler

While Next.js middleware is useful for global, high-level tasks, nextjs-centralized-error-handler enables route-specific error handling with custom error classes for fine-grained control. Here’s how both work together:

Feature	Next.js 13 Middleware	nextjs-centralized-error-handler
Scope	Global, based on route pattern matching	Route-specific, applied individually to each handler
Use Case	Authentication, global request validation	Detailed error handling, custom error messages
Custom Error Responses	Limited, generalized JSON responses	Structured, frontend-compatible JSON responses
Custom Error Classes	❌	✅
Error Logging Integration	❌	✅ (supports Sentry, Datadog, etc.)
Fine-Grained Control	❌	✅
Preventing Information Leakage	Limited, as it handles errors globally without distinguishing between error types	Enhanced, distinguishes between custom and unexpected errors to prevent sensitive data exposure
Integration with Route Handlers	Middleware runs before route handlers, cannot modify responses within handlers	Wraps individual route handlers, allowing for customized responses per route
Extensibility	Limited to what middleware can handle globally	Highly extensible through `custom error classes` and configurable options

Understanding Scope and Flexibility: Next.js Middleware vs. `nextjs-centralized-error-handler`

While Next.js middleware provides a powerful mechanism for high-level request interception, it’s important to note that middleware operates before the execution of the route handler. This means that any exceptions thrown inside the handler will not be caught by the middleware; instead, this will lead to a generic 500 Internal Server Error being returned to the client. In contrast, nextjs-centralized-error-handler excels at fine-grained error handling within individual API routes. This section clarifies their distinct roles and demonstrates how they can be used together effectively.

Scenario: User Input Validation

Imagine you are building an API route that requires a user's name to be provided in the request body. If the name is missing, you want to respond with a clear and specific error message. Let's see how each approach handles this scenario.

Using Next.js Middleware

In Next.js, middleware can be used to validate requests globally. However, it cannot catch exceptions thrown within individual route handlers.

// middleware.js

import { NextResponse } from 'next/server';

export function middleware(req) {
  try {
    // You can include any logic here that might throw an error
    return NextResponse.next(); // Proceed to the route handler
  } catch (error) {
    // Handle the error and return an appropriate response
    return NextResponse.json({ error: 'An error occurred while processing your request.' }, { status: 500 });
  }
}

// pages/api/example.js

const handler = async (req, res) => {
  if (!req.body.name) {
    throw new Error('Name is required.'); // This will not be caught by middleware
  }

  res.status(200).json({ message: `Hello, ${req.body.name}!` });
};

export default handler;

What Happens Here:

The middleware runs before the route handler to process the request.
If req.body.name is missing, the Error is thrown.
However, the middleware will not catch this error, resulting in a generic 500 Internal Server Error.

Using `nextjs-centralized-error-handler`

In contrast, nextjs-centralized-error-handler provides a higher-order function that captures errors thrown in route handlers.

// pages/api/example.js

import { errorHandler, BadRequestError } from 'nextjs-centralized-error-handler';

const handler = async (req, res) => {
  if (!req.body.name) {
    throw new BadRequestError('Name is required.'); // This will be caught by errorHandler
  }

  res.status(200).json({ message: `Hello, ${req.body.name}!` });
};

export default errorHandler(handler);

What Happens Here:

The errorHandler wraps the route handler, intercepting any errors thrown within it.
If req.body.name is missing, the BadRequestError is thrown and caught by errorHandler.
This results in a structured response with the appropriate status code (400) and a clear error message ("Name is required.").

Why Use Both Approaches Together

Combining both Next.js middleware and nextjs-centralized-error-handler provides a comprehensive error-handling strategy:

Global Request Validation and Authentication: Use Next.js middleware to handle tasks that need to be applied across multiple routes, such as authentication, authorization, and general request validation.
Route-Specific Detailed Error Handling: Use nextjs-centralized-error-handler to manage errors that occur within individual route handlers, allowing for customized and structured error responses tailored to each route's specific needs.

Example: Using Both Middleware and `nextjs-centralized-error-handler`

Middleware (middleware.js):

// middleware.js (Next.js Middleware for global authentication)

import { NextResponse } from 'next/server';

export function middleware(req) {
  if (!req.headers.get('Authorization')) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  return NextResponse.next(); // Continue to the route handler
}

export const config = {
  matcher: '/api/:path*', // Applies middleware only to /api/* routes
};

Route Handler (pages/api/example.js):

// pages/api/example.js (Using nextjs-centralized-error-handler for route-specific errors)

const { errorHandler, BadRequestError } = require('nextjs-centralized-error-handler');

const handler = async (req, res) => {
  if (!req.body.name) {
    throw new BadRequestError('Name is required.');
  }

  res.status(200).json({ message: 'Success' });
};

export default errorHandler(handler);

Explanation:

Middleware (middleware.js): Handles global tasks like authentication. Applies to all /api/* routes based on the matcher configuration.
Route Handler (example.js): Handles route-specific logic. Utilizes nextjs-centralized-error-handler for detailed error handling and structured responses.

By using Next.js middleware for request-level checks and nextjs-centralized-error-handler for response-level error handling, you achieve both broad validation and fine-grained error management.

Key Advantages of `nextjs-centralized-error-handler`:

Centralized error handling through a higher-order function.
Custom error classes to simplify and standardize error categorization.
Frontend-compatible responses, making it easier for Next.js-based frontends to parse and display error messages effectively.

Traditional Approach vs. `nextjs-centralized-error-handler`

In traditional Node.js/Express applications, centralized error handling is often managed through middleware, which intercepts requests and errors consistently across routes. In Next.js, however, API routes don’t support middleware in the same way, creating challenges for centralized error handling. nextjs-centralized-error-handler fills this gap by using a higher-order function to provide route-specific error handling across all API routes.

Traditional Approach in Express (Using Middleware)

In Express, centralized error handling is achieved through middleware functions, which allow for reusable error management across routes:

// Traditional Express Approach

const express = require('express');
const app = express();

const errorHandler = (err, req, res, next) => {
  res.status(err.status || 500).json({ message: err.message });
};

app.use('/api/example', (req, res, next) => {
  try {
    // Route handler logic
  } catch (error) {
    next(error); // Forward errors to centralized middleware
  }
}, errorHandler); // Centralized error handling middleware

In this approach, errors are passed to next(error), which then triggers centralized error-handling middleware to respond consistently across routes.

Using `nextjs-centralized-error-handler` in Next.js

With nextjs-centralized-error-handler, you get middleware-like behavior tailored for Next.js through a higher-order function (errorHandler) that wraps route handlers, intercepting and managing errors at the route level:

// Using nextjs-centralized-error-handler

const { errorHandler, BadRequestError } = require('nextjs-centralized-error-handler');

const handler = async (req, res) => {
  if (!req.body.name) {
    // Throws a custom BadRequestError with a specific error message to inform the user
    throw new BadRequestError("Name is required.");

    // Alternatively, using the default error message:
    // throw new BadRequestError();
  }
};

export default errorHandler(handler);

With nextjs-centralized-error-handler, you avoid repetitive error-handling code in each route. Instead, custom error classes and the errorHandler higher-order function provide centralized, consistent error responses, simplifying maintenance and extending error handling across the entire application.

Features

1. Centralized Error Handling

Higher-Order Error Handling: The package uses a higher-order function, errorHandler, to centralize error handling across all API routes. Rather than requiring repetitive try-catch blocks, errorHandler intercepts errors, ensuring a consistent, JSON-formatted response structure for frontend integration.

2. Structured Custom Error Classes

Customizable HTTP Error Classes: The package includes predefined classes like BadRequestError, UnauthorizedError, and NotFoundError, each mapped to an appropriate HTTP status code. This approach improves code readability and reduces redundancy, allowing developers to create additional custom error types by extending the base CustomError class.

3. JSON Serialization and Frontend Compatibility

Error Type Metadata: Serialized error responses include metadata like error type, enabling the frontend to handle specific errors consistently. This enhances the user experience by delivering clear, actionable feedback, while also ensuring sensitive server details are not exposed.

Background

What is Error Handling?

Error handling ensures that an application can respond to unexpected conditions (e.g., invalid input, lack of access) gracefully. Instead of crashing, an application with robust error handling will provide helpful feedback to users and log errors for debugging.

Challenges in Next.js API Routes

Next.js API routes support a global middleware approach, but they don’t natively support route-specific, fine-grained error handling like Express. Each route handler would otherwise need individual error management, leading to redundant code and inconsistent error responses. nextjs-centralized-error-handler addresses this by providing a higher-order function, errorHandler, that wraps route handlers to ensure consistent and centralized error handling at the route level.

Installation

Using npm

npm install nextjs-centralized-error-handler

Using Yarn

yarn add nextjs-centralized-error-handler

Usage

Basic Setup

Import errorHandler and custom error classes into your Next.js API route:

// pages/api/someEndpoint.js

const { errorHandler, BadRequestError } = require('nextjs-centralized-error-handler');

const handler = async (req, res) => {
  if (req.method !== 'GET') {
    throw new BadRequestError('Only GET requests are allowed.');
  }

  // Logic here
  res.status(200).json({ data: 'Success' });
};

export default errorHandler(handler);

Custom Error Classes

The package includes several predefined error classes:

BadRequestError (400)
UnauthorizedError (401)
ForbiddenError (403)
NotFoundError (404)
MethodNotAllowedError (405)
InternalServerError (500)
PaymentRequiredError (402)
NotAcceptableError (406)
RequestTimeoutError (408)
PayloadTooLargeError (413)
TooManyRequestsError (429)
BadGatewayError (502)
ServiceUnavailableError (503)
GatewayTimeoutError (504)
InsufficientStorageError (507)
BandwidthLimitExceededError (509)
NetworkAuthenticationRequiredError (511)

These classes simplify error creation without hardcoding status codes in each route:

// Example: Throwing an UnauthorizedError

throw new UnauthorizedError(); // Defaults to "Unauthorized access. Please log in again."

Example Usage with Default Messages

If you simply instantiate an error without specifying a message, it defaults to a pre-defined, user-friendly message.

throw new ForbiddenError(); // Defaults to "Access denied."
throw new ForbiddenError("Custom forbidden message."); // Uses custom message provided.

Creating Custom Errors

To address specific needs beyond predefined classes, the package is designed to be extensible, allowing you to create unique custom errors for advanced use cases. You can extend the base CustomError class to define your own error types, tailored to specific business logic. Here are some examples of custom errors you might create:

HTTPVersionNotSupportedError (505)
NotImplementedError (501)
VariantAlsoNegotiatesError (506)
ConflictError (409)

Example

const { CustomError } = require('nextjs-centralized-error-handler');

// Define a custom ConflictError (HTTP 409) for resource conflicts
class ConflictError extends CustomError {
  constructor(message = 'Resource conflict occurred.') {
    super(message, 409, 'ConflictError');
  }
}

// Usage
throw new ConflictError();

This example defines a custom ConflictError (HTTP 409), which can be thrown in cases where a resource conflict occurs. Creating custom errors allows you to handle unique business logic or application-specific needs efficiently.

Using `nextjs-centralized-error-handler` with App Router

In addition to supporting traditional API routes, nextjs-centralized-error-handler can also be utilized with the App Router introduced in Next.js 13. Here’s how to implement error handling in your App Router using the package.

Example: Using `nextjs-centralized-error-handler` with the App Router

Creating a Route with Error Handling

You can create a route in your App Router and use the error handler to manage errors effectively.

// app/api/hello/route.js

import { errorHandler, BadRequestError } from 'nextjs-centralized-error-handler';

const handler = async (req) => {
  const { name } = req.body;

  if (!name) {
    throw new BadRequestError('Name is required.'); // This error will be handled by the errorHandler
  }

  return new Response(JSON.stringify({ message: `Hello, ${name}!` }), {
    status: 200,
    headers: { 'Content-Type': 'application/json' },
  });
};

// Wrap the handler with errorHandler for centralized error management

export const GET = errorHandler(handler);
export const POST = errorHandler(handler); // Example for handling POST requests

Explanation

Handler Function: The handler function processes incoming requests. It checks for a name parameter and throws a BadRequestError if it's missing.
Error Handling: The handler is wrapped with errorHandler, which captures any errors thrown during execution and returns a structured error response.

Error Handling in App Router

Using the App Router allows for a clean and structured way to manage errors while leveraging the powerful capabilities of nextjs-centralized-error-handler. By combining both, you ensure that your application handles errors effectively, regardless of the routing method used.

Customizing Error Handling Behavior

Beyond custom errors, this package allows developers to fully control the behavior of error handling by:

Custom Logging: You can plug in any logging function to track errors. This includes integrating external services (e.g., Sentry, LogRocket) or custom loggers.
Error Message Formatting: Use formatError to add custom fields (e.g., requestId, timestamp).
Default Status and Messages: Control defaults for unhandled errors, ensuring user-friendly feedback without exposing server details.

Error Handler Options

You can configure the errorHandler with options for custom logging, error formatting, and default messages:

const handler = async (req, res) => {
  // Handler logic
};

const options = {
  logger: customLoggerFunction, // Optional custom logger
  defaultStatusCode: 500,
  defaultMessage: 'Something went wrong!',
  formatError: (error, req) => ({
    message: error.message,
    type: error.name,
    timestamp: new Date().toISOString(),
    path: req.url, // Adds request URL path to the error response
  }),
};

export default errorHandler(handler, options);

Additional Examples for formatError

The formatError function is highly flexible, allowing you to create detailed and structured error responses that fit your application’s requirements. Below are some example configurations showcasing the versatility of formatError:

Adding User and Request Information

const formatError = (error, req) => ({
  message: error.message,
  type: error.name,
  timestamp: new Date().toISOString(),
  path: req.url,
  userId: req.user?.id || 'guest', // Captures user ID if available
  requestId: req.headers['x-request-id'] || 'N/A', // Useful for tracing requests
});

Including Detailed Stack Trace for Development

const formatError = (error, req) => ({
  message: error.message,
  type: error.name,
  timestamp: new Date().toISOString(),
  stack: process.env.NODE_ENV === 'development' ? error.stack : undefined, // Include stack trace only in development
});

Integrating Application Metadata

const formatError = (error, req) => ({
  message: error.message,
  type: error.name,
  timestamp: new Date().toISOString(),
  appVersion: process.env.APP_VERSION || '1.0.0', // Adding application version to help track error sources
  environment: process.env.NODE_ENV,
});

Customizing Error Responses

The formatError function provides the flexibility to add or omit fields based on your requirements, making it easy to generate structured, informative error responses. These options make the package adaptable to diverse applications by providing developers the ability to standardize error messaging and traceability across their API.

Security Considerations

Comprehensive Exception Handling

The errorHandler higher-order function wraps each route handler individually, capturing all exceptions—both expected and unexpected—without requiring repetitive try-catch blocks. This approach ensures that even third-party or unforeseen errors are intercepted, allowing for consistent and secure error responses across all routes.

Preventing Information Leakage

To protect sensitive data, our package distinguishes between intentional, known errors (e.g., CustomError instances) and unexpected errors:

Custom Errors Only: Only errors created as instances of CustomError (or its subclasses) include their statusCode and message in the client response, providing clear, user-friendly error feedback for known issues.
Generic Handling of Unexpected Errors: For errors that aren’t instances of CustomError—such as third-party library issues or unforeseen server errors—errorHandler automatically applies a status code of 500 and a generic message ("An internal server error occurred"). This prevents sensitive information from being inadvertently exposed to clients.

Customizable Logging for Security and Monitoring

While keeping responses to the client secure and generalized, errorHandler also supports server-side logging. This allows unexpected errors to be logged and monitored internally without revealing details to the client, combining security with effective error tracking.

Example: Handling Unexpected Errors Safely

Consider an API route that relies on a third-party library, which may throw errors we can’t predict:

const { errorHandler } = require('nextjs-centralized-error-handler');

const handler = async (req, res) => {
  // An error from a third-party library
  await thirdPartyLibrary.doSomething(); // Throws an unexpected error
};

export default errorHandler(handler);

What Happens Under the Hood

If thirdPartyLibrary.doSomething() throws an error that isn’t a CustomError, errorHandler will:

Set statusCode to 500 (or the configured defaultStatusCode).
Set message to "An internal server error occurred. Please try again later." (or defaultMessage if configured).
Prevent Information Leakage: Ensures no sensitive details (e.g., the original error message or stack trace) are sent to the client.
Log the Error Server-Side: Uses the provided logger for internal monitoring to record the error.

Note on Error Handling Strategy

The errorHandler function distinguishes between custom errors and unexpected errors:

Custom Errors (CustomError instances): The specific statusCode and message you define are sent to the client, offering clear and user-friendly feedback for known issues.
Other Errors: A default statusCode and message are used to safeguard against information leakage from unexpected errors.

By catching all errors in this way, nextjs-centralized-error-handler provides a robust, secure, and unified error-handling solution tailored for Next.js applications, with built-in protections to prevent unintended data exposure.

Examples

Below are real-world scenarios demonstrating how nextjs-centralized-error-handler can simplify error handling across various use cases.

Note: If an error is instantiated without a specific message, a default, user-friendly message is provided automatically.

1. Handling Different HTTP Methods

Use Case: Ensure that only specific HTTP methods (e.g., POST) are allowed for an API route and provide a meaningful error message if the method is incorrect.

In this example, MethodNotAllowedError is thrown if the incoming request uses any method other than POST, ensuring consistent, user-friendly feedback. If no custom message is provided, the default message, "Method not allowed," will be used.

const { errorHandler, MethodNotAllowedError } = require('nextjs-centralized-error-handler');

const handler = async (req, res) => {
  if (req.method !== 'POST') {
    throw new MethodNotAllowedError(); // Uses default message
  }

  // Logic for handling POST requests
  res.status(200).json({ message: 'POST request successful' });
};

export default errorHandler(handler);

2. Validating Request Parameters

Use Case: Check for the presence of required parameters in the request and respond with a structured error if validation fails.

Here, BadRequestError is thrown when a required parameter (name) is missing. If no custom message is specified, the default message, "It seems there was an error with your request," is used.

const { errorHandler, BadRequestError } = require('nextjs-centralized-error-handler');

const handler = async (req, res) => {
  const { name } = req.body;

  if (!name) {
    throw new BadRequestError(); // Uses default message
  }

  // Continue processing if name is provided
  res.status(200).json({ message: `Hello, ${name}!` });
};

export default errorHandler(handler);

3. Handling Unauthorized Access

Use Case: Restrict access to authorized users only. If the user is not authenticated, respond with an UnauthorizedError to signal unauthorized access.

In this example, UnauthorizedError is used to ensure only authenticated users can access the route. If no custom message is provided, it defaults to "Unauthorized access. Please log in."

const { errorHandler, UnauthorizedError } = require('nextjs-centralized-error-handler');

const handler = async (req, res) => {
  const { isAuthenticated } = req;

  if (!isAuthenticated) {
    throw new UnauthorizedError(); // Uses default message
  }

  res.status(200).json({ message: 'Welcome, authenticated user!' });
};

export default errorHandler(handler);

4. Enforcing Payload Limits

Use Case: Reject requests that contain a payload exceeding a defined size, helping to prevent misuse or denial-of-service attacks.

If the payload exceeds a specific limit, PayloadTooLargeError is thrown to inform the client. Without a custom message, the default message, "Request entity too large," will be displayed.

const { errorHandler, PayloadTooLargeError } = require('nextjs-centralized-error-handler');

const handler = async (req, res) => {
  const MAX_PAYLOAD_SIZE = 1024 * 1024; // 1 MB

  if (req.headers['content-length'] > MAX_PAYLOAD_SIZE) {
    throw new PayloadTooLargeError(); // Uses default message
  }

  res.status(200).json({ message: 'Payload accepted.' });
};

export default errorHandler(handler);

5. Customizing Error Responses (Advanced)

If you want to include additional metadata or customize error responses, nextjs-centralized-error-handler allows you to define a formatError function. This function can be tailored to include extra fields, such as request paths or timestamps.

For full details, see the Customizing Error Handling Behavior section. Here's a quick example:

const { errorHandler, InternalServerError } = require('nextjs-centralized-error-handler');

const handler = async (req, res) => {
  throw new InternalServerError("Custom error occurred.");
};

const options = {
  formatError: (error, req) => ({
    message: error.message,
    type: error.name,
    timestamp: new Date().toISOString(),
    path: req.url,
  })
};

export default errorHandler(handler, options);

Integration with Logging Services

To enhance observability, nextjs-centralized-error-handler supports custom logging through any service, such as Sentry, Datadog, or a custom logging solution. By passing a logging function (such as Sentry.captureException) to errorHandler, you can monitor errors in real-time while ensuring security and efficiency.

What is a Custom Logger?

A "custom logger" is any logging function or external service (such as console.log, Sentry.captureException, or a custom implementation) that you provide to errorHandler to log errors server-side. This logging function is not part of nextjs-centralized-error-handler itself, but the package is designed to integrate seamlessly with the logger of your choice.

Best Practices for Secure Logging

Avoid Logging Sensitive Data: Ensure that your custom logger does not inadvertently log sensitive user data, such as credentials or personal details. Limit logs to essential error information only to maintain security and compliance with data protection standards.

Enhanced Logging with Sentry

If you’re using Sentry, a popular monitoring tool, you can integrate it with this package for production error tracking:

Note on Sentry: Sentry helps developers track, debug, and resolve issues in real time. Integrating Sentry with nextjs-centralized-error-handler allows you to log errors in production, providing insight into where and why failures occur without exposing sensitive details.

The example below demonstrates how to use Sentry’s captureException function as a logger with errorHandler.

const Sentry = require('@sentry/node');
const { errorHandler, InternalServerError } = require('nextjs-centralized-error-handler');

// Initialize Sentry with your DSN
Sentry.init({ dsn: 'your-sentry-dsn' });

const handler = async (req, res) => {
  // Logic that could throw an InternalServerError
  throw new InternalServerError();
};

// Wrap handler with errorHandler, using Sentry to capture exceptions
export default errorHandler(handler, { logger: Sentry.captureException });

This setup captures errors for monitoring, while safeguarding against exposing sensitive information to clients. By leveraging custom loggers, nextjs-centralized-error-handler combines robust security with effective error tracking, ensuring a secure and observable application environment.

Community Feedback and Stability

As this package is newly released, I am aware of the importance of stability in production environments. While I have conducted testing, the real-world usage and feedback from the community are crucial for identifying any potential issues and improving the package further.

I encourage developers to integrate nextjs-centralized-error-handler into their projects and share their experiences. Whether it’s bug reports, suggestions for improvement, or simply sharing how it has helped streamline error management in your applications, your feedback is invaluable. Together, we can enhance this package and make it even more effective for the Next.js community.

Benefits at a Glance

Tailored for Next.js: Handles Next.js API route limitations with centralized error handling.
Custom Error Classes: Predefined and extensible classes for structured error management.
JSON-Formatted Responses: Frontend-compatible and metadata-enriched error messages.
Customizable Logging: Integration with third-party logging services for error monitoring.
Seamless Integration: Quickly adaptable to existing Next.js applications.

Conclusion:

I hope that nextjs-centralized-error-handler will greatly enhance error management for Next.js developers, offering a comprehensive and user-friendly approach to handling errors. By centralizing error management, leveraging custom error classes, and integrating smoothly with logging services, this package tackles common pain points in Next.js application development.

I invite the dev.to community to provide feedback and contribute to the project, as your insights are invaluable for refining this package. You can check out the package on npm and explore the GitHub repository for further details!

Explore the package and contribute to its development:

Your input is crucial for identifying issues and enhancing stability. I encourage you to experiment with nextjs-centralized-error-handler and share your experiences. Together, we can advance this package for the Next.js community.

Thank you for your support, and I’m excited to hear your thoughts and experiences!

DEV Community: Riyon Sebastian

How I Started Capturing What Actually Happens When an API Fails

Most monitoring tools tell you one thing

The frustrating part of debugging failures

Logs don't always tell the full story

Breaking down an HTTP request

The idea: capture the failure at the moment it happens

What this actually changes

Example A — Server degradation into timeout

Example B — Upstream dependency failure

The tricky part: getting this data in Node.js

One more design decision: don't alert on the first failure

A small shift in thinking

Still exploring

Building a Robust Frontend Error-Handling System with Axios and Custom Hooks

Introduction

📚 Free Udemy Course (Structured Content)

🎥 Watch the Full Tutorial on YouTube

🛠️ Explore the Source Code on GitHub

Hook: Why Centralized Error Handling Matters

Table of Contents

Why Centralized Error Handling?

Repetitive Error Code

Inconsistent User Experience

Basic Implementation

Setting Up the Axios Instance with Interceptors

Custom Error Messages

Quick Summary: Axios Interceptor Configuration

Creating the Custom useApi Hook

Parameters:

Returned Values:

Implementation:

Explanation:

Understanding Promises and Promise Rejection

Relevance in Axios and useApi:

Importance of Handling Promise Rejections:

What If useApi Hook Isn't Used?

Example Usage:

Organizing Service Modules

Example: Product Service

Example: User Service

Benefits of Service Modules:

Advanced Enhancements (Optional)

Error Parsing Customization

Retry Mechanism

Detailed Notifications

Cancel Requests on Component Unmount

Advanced Enhancements Summary

Connecting Dots

Components Use Service Modules:

useApi Triggers Axios via the Service Module:

Custom Error Parsing in Axios Interceptors:

Structured Responses from useApi:

Visual Summary

Putting It All Together: A Real-World Example

ProductList Component

Component Breakdown:

Best Practices

Separation of Concerns

Consistent Error Messaging

Avoid Repetitive Code

Meaningful Error Messages

Handle Edge Cases

Secure Error Handling

Further Reading

Troubleshooting

1. Toast Notifications Not Appearing

2. API Requests Not Caught by Interceptors

3. Redirects Not Working on Specific Errors

Environment Configuration

Step 1: Define Environment Variables

Step 2: Access Environment Variables in Code

Best Practices:

Conclusion

Call to Action

Ready to enhance your React/Next.js applications with centralized error handling?

Share Your Feedback

Stay Tuned for More

Efficiently Manage Errors in Next.js with a Comprehensive Developer Solution

Introduction

Creating the Custom `useApi` Hook

Relevance in Axios and `useApi`:

What If `useApi` Hook Isn't Used?

`useApi` Triggers Axios via the Service Module:

Structured Responses from `useApi`:

Why Use `nextjs-centralized-error-handler` with Next.js Middleware?

Understanding Scope and Flexibility: Next.js Middleware vs. `nextjs-centralized-error-handler`

Using `nextjs-centralized-error-handler`

Example: Using Both Middleware and `nextjs-centralized-error-handler`

Key Advantages of `nextjs-centralized-error-handler`:

Traditional Approach vs. `nextjs-centralized-error-handler`

Using `nextjs-centralized-error-handler` in Next.js

Using `nextjs-centralized-error-handler` with App Router

Example: Using `nextjs-centralized-error-handler` with the App Router