How to Handle and Return Errors in a REST API

Error handling is a fundamental aspect of API design, as unexpected failures can disrupt client applications and degrade the user experience. Well-structured error responses guide developers to quickly identify issues and implement fixes, reducing debugging time and support overhead.

If you’re designing your API endpoints from scratch or revisiting your structure, check out our REST API Endpoint Design Guide for best practices that support clean, maintainable routing and easier error tracking.

Consistent and clear error messages ensure that clients can programmatically respond to errors and present helpful feedback to end users. Standardizing error formats, such as adopting the RFC 7807 "Problem Details" model, avoids ambiguity and improves interoperability across different services and tooling. If you’re new to building APIs and want to understand the basics before tackling error handling, check out our guide on creating a simple REST API with JSON.

In this article, we will explore how to categorize errors into client-side (4xx) and server-side (5xx) responses, select appropriate HTTP status codes for common scenarios such as validation failures and resource conflicts, and define a unified JSON structure for conveying error details. 

You will also learn how to implement centralized error‑handling middleware in Express, integrate input validation with libraries like express‑validator, adopt security best practices to avoid leaking internal information, and set up logging and monitoring to track and diagnose issues in production.

Understanding Error Categories in REST APIs

Errors in REST APIs fall into two primary categories: client errors (4xx) and server errors (5xx), each indicating who is responsible for the failure and what action is required to resolve it.

Client errors indicate that the request itself is invalid or cannot be fulfilled without modification, while server errors signal that the server failed to process a valid request. Embedding error details within a 200-level response may appear convenient, but it breaks HTTP semantics, hinders client libraries from automatically detecting failures, and complicates monitoring and retries.

Client Errors (4xx)

Client error codes tell consumers that something is wrong with the request:

• 400 Bad Request: The server cannot process requests with malformed syntax or invalid data.
• 401 Unauthorized: Authentication is required or has failed; the client must supply valid credentials.
• 403 Forbidden: The client is authenticated but lacks permission to access the resource.
• 404 Not Found: The requested resource does not exist at the given URI.
• 409 Conflict: The request could not be completed due to a conflict with the current state of the target resource (e.g., duplicate entries).
• 422 Unprocessable Entity: The request is syntactically correct but semantically invalid (often used for detailed validation failures).

Using precise 4xx codes helps clients distinguish between retryable issues (e.g., 400 vs. 409) and permanently invalid requests (e.g., 404).

Server Errors (5xx)

Server error codes indicate that the server encountered an unexpected condition while processing a valid request:

• 500 Internal Server Error: A generic, catch‑all error for unhandled exceptions or failures in server logic.
• 503 Service Unavailable: Indicates that the server is temporarily unable to handle the request (due to overload or maintenance) and that the client may retry the request later.

Properly using 5xx codes enables clients and intermediaries to implement exponential backoff, circuit breakers, and other resilience patterns.

Use Cases for 200-Level Responses With Embedded Errors (and Why to Avoid)

Some batch or RPC-style APIs return HTTP 200 OK even when individual operations within the payload fail, embedding error details in the response body. While this can simplify single-channel error parsing, it:

1. Breaks Semantics: Clients and proxies treat 200 responses as successful, masking failures from monitoring and alerting systems.
2. Complicates Client Code: Consumers must inspect response bodies for error flags instead of relying on standard HTTP status workflows.
3. Hinders Caching and Retries: HTTP caches and client libraries generally do not retry 200 responses, even if they contain errors, reducing resilience.

Best Practice: Use appropriate 4xx/5xx status codes for failure scenarios. For partial successes, consider 207 Multi-Status or redesigning endpoints to return homogeneous results per request.

Choosing the Right HTTP Status Codes

HTTP status codes are standardized indicators of request outcomes, allowing clients to understand whether a request succeeded, failed due to client-side issues, or encountered server-side problems. Selecting the most accurate code improves clarity, aids debugging, and aligns your API with HTTP semantics.

400 Bad Request

The HTTP 400 Bad Request status code indicates the server cannot process the request due to malformed syntax, invalid message framing, or deceptive routing. Clients should not retry the identical request without modification.

401 Unauthorized / 403 Forbidden

• 401 Unauthorized: Returned when authentication is required or has failed; the client must supply valid credentials to proceed.
• 403 Forbidden: Indicates the server understood the authenticated request but refuses to authorize it, typically due to insufficient permissions; even valid credentials won’t help.

404 Not Found

The server uses the HTTP 404 Not Found status code to tell clients it cannot locate the requested resource. Developers often use it when the endpoint exists but the specific item does not, or to hide the existence of a resource from unauthorized users.

409 Conflict

The HTTP 409 Conflict status code indicates that the server cannot complete the request because it conflicts with the current state of the target resource, such as when a client attempts to create a duplicate entry or modify a resource that is already being edited.

422 Unprocessable Entity

The HTTP 422 Unprocessable Entity status code means the server understands the request’s content type and syntax but cannot process the contained instructions due to semantic errors, making it ideal for detailed validation failures.

500 Internal Server Error

An HTTP 500 Internal Server Error is a generic catch-all error that indicates the server encountered an unexpected condition, preventing it from fulfilling the request. It signals server-side faults and should trigger internal logging for further investigation.

Standardizing Error Response Format

A consistent JSON error structure ensures that client applications can reliably parse and respond to failures, reduces ambiguity during debugging, and aligns your API with established standards, such as RFC 7807 (“Problem Details for HTTP APIs”). 

By defining an explicit schema that includes a top-level problem descriptor, HTTP status, descriptive titles, and optional metadata, you simplify client integration, improve observability, and streamline error handling across your entire service landscape.

Why a Consistent Structure Matters

• Predictable Parsing: Clients know exactly where to look for error details, eliminating the need for ad-hoc checks and custom logic for each endpoint.
• Developer Experience: Standardized fields like title and detail provide clear, actionable messages, reducing context switching and support overhead.
• Tooling & Interoperability: Adhering to RFC 7807’s media type (application/problem+json) enables off-the-shelf libraries and API clients to handle errors without requiring custom adapters.
• Observability: Uniform error payloads facilitate centralized logging, automated alerts, and dashboarding by ensuring that logs and metrics extract the same fields across services.

Recommended JSON Schema

Following RFC 7807, a minimal “Problem Details” object includes these members:

{
  "type": "https://example.com/probs/invalid-input",
  "title": "Invalid input data",
  "status": 422,
  "detail": "Your request parameters didn't pass validation",
  "instance": "/api/users"
}

• title (string): A brief, human‑readable summary of the problem.
• status (number): The HTTP status code generated by the origin server for this occurrence of the problem.
• detail (string): A human-readable explanation specific to this error occurrence.
• instance (string): A URI that identifies the specific occurrence of the problem (e.g., the request path).

Extending With Optional Fields

To enrich the error context, consider these additional members:

• errors (array): An array of field‑level issues, each with field and issue properties (inspired by JSON: API’s errors array).
• timestamp (string): ISO 8601 timestamp of when the error occurred, aiding correlation across logs.
• requestId (string): A unique identifier for the request, useful for end‑to‑end tracing.
• stackTrace (string): Include only in non‑production environments to avoid exposing internal logic.

Example: Detailed Error Response

{
  "type": "https://api.example.com/problems/validation-error",
  "title": "Validation Failed",
  "status": 422,
  "detail": "One or more input fields failed validation",
  "instance": "/api/users",
  "errors": [
    {
      "field": "email",
      "issue": "Email is required"
    },
    {
      "field": "age",
      "issue": "Must be a positive integer"
    }
  ],
  "timestamp": "2025-04-21T10:15:30Z",
  "requestId": "abc123xyz"
}

By adopting this standardized format, you ensure that all clients, from web frontends to mobile apps and third-party services, can uniformly detect, display, and log API errors, resulting in a more robust and maintainable system.

Implementing Error Handling in Your API (Example in JavaScript/Express)

In this section, you’ll learn how to surface errors from your route handlers using next() or a helper library, funnel all errors through a centralized middleware, and customize the JSON payload returned based on the error’s type or status code.

Throwing Errors in Route Handlers

When an error occurs in a route, forward it to the error‑handling middleware rather than handling it inline. You can do this by calling next(err) or by using the http-errors module’s createError helper:

const createError = require('http-errors');

app.get('/api/item/:id', (req, res, next) => {
  const item = findItem(req.params.id);
  if (!item) {
    // Create a 404 Not Found error and pass to next()
    return next(createError(404, 'Item not found'));
  }
  res.json(item);
});

This approach ensures consistency in how errors are constructed and handed off to the centralized handler.

For asynchronous route handlers, wrap logic in a try…catch block and forward the error, or use a helper to auto‑catch Promise rejections:

app.post('/api/users', async (req, res, next) => {
  try {
    const user = await createUser(req.body);
    res.status(201).json(user);
  } catch (err) {
    next(err);
  }
});

This pattern prevents unhandled Promise rejections and routes all failures through the same error pipeline.

Centralized Error-Handling Middleware

Express recognizes error‑handling middleware by its four-argument signature (err, req, res, next). Place this after all other routes and middleware:

// Central error handler
app.use((err, req, res, next) => {
  // If headers are already sent, delegate to default handler
  if (res.headersSent) {
    return next(err);
  }
  
  // Default to 500 if status not set
  const status = err.status || 500;
  
  // Send standardized JSON error response
  res.status(status).json({
    error: {
      message: err.message,
      code: status,
      // Optional details from custom errors
      details: err.details || null
    }
  });
});

This middleware catches every error forwarded via next(err), logs or processes it as needed, and returns a uniform JSON structure.

You can also leverage the built‑in errorhandler module during development to get stack traces automatically injected into responses when in non‑production environments.

Customizing and Returning Error Responses

To differentiate error payloads further, you can detect custom error properties (e.g., err.type, err.details) and augment the JSON response:

app.use((err, req, res, next) => {
  if (res.headersSent) {
    return next(err);
  }
  const status = err.status || 500;
  const response = {
    type: err.type || 'about:blank',
    title: err.title || err.message,
    status,
    detail: err.detail || null
  };
  
  // Attach validation errors if present
  if (err.errors) {
    response.errors = err.errors;
  }
  
  res.status(status).json(response);
});

Including fields like type, title, and an errors array aligns with best practices and aids client‑side error handling.

For validation-specific errors (e.g., using express-validator), you might detect and reformat them before they hit the client:

const { validationResult } = require('express-validator');

app.post('/api/register', validators, (req, res, next) => {
  const errors = validationResult(req);
  if (!errors.isEmpty()) {
    const err = createError(422, 'Validation Failed');
    err.errors = errors.array().map(e => ({ field: e.param, issue: e.msg }));
    return next(err);
  }
  // Continue with successful flow...
});

This pattern ensures that clients receive granular, field-level feedback in a consistent schema.

By following these steps, handling errors in handlers, consolidating them in a centralized middleware, and tailoring the JSON response, you establish a robust and maintainable error strategy that enhances both the developer experience and client integration.

Handling Validation Errors

Handling validation errors ensures that your API rejects improper requests and provides clients with actionable feedback to correct submissions.

Detecting Invalid Input

Using express-validator

The express-validator library offers middleware to declare validation rules on request parameters or body fields, catching missing or incorrectly typed inputs before they reach your business logic.

To require an email field that must be non-empty and follow a valid email pattern, you can use validation chains like body('email').notEmpty() and body('email').isEmail() from express-validator. When defining route handlers, include these validators as middleware to flag invalid requests early.

Using Joi

The Joi library enables schema-based validation by defining an object schema that outlines expected types and constraints, then validating the incoming req.body against it. For example, you might create a schema requiring username as a non-empty string and age as a positive integer:

const Joi = require('joi');
const schema = Joi.object({
  username: Joi.string().required(),
  age: Joi.number().integer().min(0).required()
});
const { error, value } = schema.validate(req.body, { abortEarly: false });

If any fields fail validation, error.details provides an array of issues for each field.

Returning Detailed Messages for Each Field

With express-validator

After running validations, use validationResult(req) to collect errors and format them in your response. For instance:

const { validationResult } = require('express-validator');
app.post('/api/users', validators, (req, res) => {
  const errors = validationResult(req);
  if (!errors.isEmpty()) {
    return res.status(422).json({
      errors: errors.array().map(err => ({
        field: err.param,
        message: err.msg
      }))
    });
  }
  // process valid data...
});

Each object in the errors array contains the parameter name and the custom message defined in your validation chain.

With Joi

When using Joi, you can include all validation errors by setting abortEarly: false. Then map error details to your response structure:

if (error) {
  const formatted = error.details.map(e => ({
    field: e.path.join('.'),
    message: e.message
  }));
  return res.status(422).json({ errors: formatted });
}

This approach returns clear, per-field messages that clients can display or log, improving integration troubleshooting.

Optional Libraries and Tools

Beyond express-validator and Joi, you can explore express-joi-validation, which combines Joi schemas with Express middleware for streamlined validation and error handling in TypeScript‑friendly environments.

Security Considerations

Implementing secure error handling is essential to prevent information leakage, reduce your API’s attack surface, and ensure clients receive only the information they need to recover safely. Key practices include hiding stack traces and internal details, using generic messages for authentication and authorization failures, logging errors internally for debugging purposes, disabling debug modes in production environments, and applying rate limiting to prevent abuse and enumeration. 

Avoid Exposing Internal Details

Never return stack traces or internal exception messages in production responses, as they can reveal library versions, file paths, and code structure that attackers can exploit. Ensure your error handler strips out any stack trace information and only exposes a minimal, user‑friendly message. 

Use Generic Messages for Authentication/Authorization Failures

For authentication and authorization errors (401/403), provide a generic response such as “Unauthorized” or “Access denied” without specifying whether the credentials were invalid or the user lacks specific permissions. This prevents attackers from inferring valid usernames or permission boundaries from error responses.

Log Errors Internally

While hiding details from clients, capture complete error information, including stack traces and request context, in your internal logs. Utilize a structured logging framework to record error levels, timestamps, request IDs, and user context, allowing for efficient debugging without compromising production security.

Disable Debug Mode in Production

Frameworks often include debug modes that automatically generate detailed error pages with stack traces. Always disable debug and developer‑friendly error pages in your production environment to avoid accidental exposure of sensitive implementation details.

Implement Rate Limiting and Throttling

Apply rate limits on error‑returning endpoints to mitigate brute‑force and enumeration attacks. Limiting the number of failed authentication attempts or error‑triggering requests per client within a time window helps protect against credential stuffing and mass probing. Return a 429 Too Many Requests status when limits are exceeded, and include Retry-After headers to inform clients when to retry.

By following these security considerations, hiding internal details, using generic messages, logging safely, disabling debug features, and enforcing rate limits, you ensure that your API handles errors robustly without exposing sensitive information or enabling abusive behavior.

Logging and Monitoring

Effective logging and monitoring form the backbone of resilient REST APIs, enabling the rapid identification, diagnosis, and resolution of issues before they impact end users. Structured logs capture essential context, such as timestamps, request IDs, and error levels, that simplify troubleshooting and support automated analysis. 

Centralizing these logs in aggregation systems and pairing them with real‑time alerts and anomaly detection ensures you can proactively detect failures, track their root causes, and maintain high service reliability.

Structured and Correlated Logging

• Structured (JSON) Logging: Use a logging library like Winston or Morgan in Node.js to emit logs in JSON format, including fields such as timestamp, level, message, and contextual metadata. This approach enables machines and log management tools to parse and index logs efficiently, thereby enhancing their effectiveness.
• Correlation IDs: Generate a unique correlation ID for each incoming request and propagate it through service calls. Including this ID in every log entry allows you to trace a request’s journey across distributed components, simplifying root‑cause analysis.

Centralized Log Aggregation

• ELK Stack (Elasticsearch, Logstash, Kibana): Aggregate and search logs using the open‑source ELK Stack. Shipping logs from your Node.js Express application to Elasticsearch via Logstash or Beats and visualizing them in Kibana helps you spot error patterns and performance bottlenecks.
• Hosted Solution (Treblle): For hosted solutions, Treblle’s Custom Alerts feature allows you to set thresholds on error rates or response time for specific endpoints or saved searches, sending notifications via email, Slack, or in‑app to the right recipients and reducing alert fatigue by filtering out noise 

Real-Time Monitoring and Alerting

• Anomaly Detection: Utilize AI-driven monitoring tools that analyze baseline metrics and identify deviations, thereby reducing the mean time to detect (MTTD) and resolve (MTTR) incidents. Studies show this can cut API failures by up to 60%.
• Error Dashboards: Use platforms like Grafana to create dashboards that surface error counts, rates, and latencies. Grafana’s error awareness features enable you to drill into specific event instances and perform root-cause analysis with trace context.
• API Observability (Treblle): Integrate Treblle to capture detailed error logs, categorize them by threat level, and receive real‑time notifications when error thresholds are crossed, enabling swift issue resolution.

Log Levels and Best Practices

• Consistent Levels: Adopt a standard set of log levels, such as debug, info, warn, error, and fatal, to differentiate between debugging information, operational warnings, and critical failures.
• Avoid Sensitive Data: Never log personal or sensitive information, such as passwords and tokens. Follow OWASP guidelines to prevent accidental exposure through logs.

Observability Platforms Comparison

• Treblle: Designed for REST API observability, providing auto‑generated dashboards for errors, performance, and security insights.
• Grafana: Open‑source dashboards with plugins for logs, metrics, and traces, enabling deep exploration of error events.
• BetterStack: Offers end‑to‑end API monitoring with real‑time checks, traces, and incident management in a unified platform.

For a broader look at the leading solutions in this space, explore our roundup of the Top 10 API Observability Tools in 2025—including feature comparisons, pricing, and ideal use cases.

By employing structured logging, aggregating logs centrally, setting up real-time alerts, and leveraging observability platforms, you can build a proactive monitoring strategy that keeps your REST APIs reliable, maintainable, and responsive to operational challenges.

Wrap Up

Proper error handling is vital for building reliable and user‑friendly APIs. Embracing an API-first mindset ensures your API design prioritizes clarity, stability, and tooling compatibility from the start, reducing costly iterations and misunderstandings later in the development cycle.

By categorizing errors into client (4xx) and server (5xx) types, selecting precise HTTP status codes, and adhering to a standardized JSON error schema, you provide clients with the clarity they need to react programmatically and troubleshoot effectively.

By centralizing error logic in Express middleware, integrating robust validation using tools like express-validator or Joi, and following security best practices such as hiding stack traces and enforcing rate limits, developers can manage failures consistently and securely.

Pairing your error strategy with structured logging and real‑time monitoring creates an observability loop that allows you to detect, diagnose, and resolve issues before they become critical.

For an end‑to‑end solution, consider integrating Treblle into your API workflow. Treblle automatically detects and categorizes API errors, security risks, and documentation issues, offering real‑time insights into every request. 

You can configure custom alerts to receive notifications via email, Slack, or in-app channels whenever error thresholds are exceeded, ensuring you catch critical failures immediately. Treblle’s observability platform provides a straightforward setup with minimal configuration and no code changes, offering clear dashboards to monitor performance metrics, traces, and error trends in one place.

By combining a solid error‑handling foundation with Treblle’s API intelligence, you’ll maintain high API quality, enhance developer experience, and deliver a more resilient service.