Error Handling in REST APIs — Status Codes and Responses Guide

{
  "status": 400,
  "error": "validation_error",
  "message": "Validation failed for the request",
  "details": [
    {
      "field": "email",
      "code": "invalid_email",
      "message": "The provided email address is not valid",
      "value": "not-an-email]
    }
  ],
  "requestId": "req_abc123",
  "documentationUrl": "https://docs.dodatech.com/api/errors#validation_error",
  "timestamp": "2026-06-23T10:00:00Z"
}

const ERROR_CODES = {
  VALIDATION_ERROR: "validation_error",
  NOT_FOUND: "not_found",
  UNAUTHORIZED: "unauthorized",
  FORBIDDEN: "forbidden",
  CONFLICT: "conflict",
  RATE_LIMITED: "rate_limited",
  INTERNAL_ERROR: "internal_error",
  SERVICE_UNAVAILABLE: "service_unavailable",
  DEPENDENCY_FAILURE: "dependency_failure",
  INVALID_STATE: "invalid_state"
};

// Create a custom error class
class ApiError extends Error {
  constructor(statusCode, error, message, details = null) {
    super(message);
    this.statusCode = statusCode;
    this.error = error;
    this.details = details;
    this.requestId = generateRequestId();
    this.timestamp = new Date().toISOString();
  }
}

// Error factory functions
const Errors = {
  badRequest: (msg, details) =>
    new ApiError(400, "bad_request", msg, details),
  unauthorized: (msg = "Authentication required") =>
    new ApiError(401, "unauthorized", msg),
  forbidden: (msg = "Insufficient permissions") =>
    new ApiError(403, "forbidden", msg),
  notFound: (resource = "Resource") =>
    new ApiError(404, "not_found", `${resource} not found`),
  conflict: (msg) =>
    new ApiError(409, "conflict", msg),
  validationError: (details) =>
    new ApiError(422, "validation_error", "Validation failed", details),
  tooManyRequests: () =>
    new ApiError(429, "rate_limited", "Rate limit exceeded, please try again later"),
  internal: (msg = "Internal server error") =>
    new ApiError(500, "internal_error", msg)
};

// Throw errors in controllers
app.get("/api/users/:id", async (req, res, next) => {
  try {
    const user = await userModel.findById(req.params.id);
    if (!user) {
      throw Errors.notFound("User");
    }
    res.json({ success: true, data: user });
  } catch (error) {
    next(error);
  }
});

// Global error handler middleware
app.use((err, req, res, next) => {
  // Log the error
  console.error(`[${err.requestId}] ${err.statusCode || 500}: ${err.message}`);

  // Determine status code
  const statusCode = err.statusCode || 500;
  const error = err.error || "internal_error";
  const message = statusCode === 500
    ? "An unexpected error occurred"
    : err.message;

  // Build response
  const response = {
    status: statusCode,
    error,
    message,
    requestId: err.requestId || generateRequestId(),
    timestamp: err.timestamp || new Date().toISOString()
  };

  // Include details for validation errors
  if (err.details) {
    response.details = err.details;
  }

  // Include documentation URL for known errors
  if (ERROR_DOCS[error]) {
    response.documentationUrl = ERROR_DOCS[error];
  }

  // In development, include stack trace
  if (process.env.NODE_ENV === "development") {
    response.stack = err.stack;
  }

  res.status(statusCode).json(response);
});

from fastapi import FastAPI, HTTPException, Request
from fastapi.responses import JSONResponse
import uuid
from datetime import datetime

app = FastAPI()

class ApiError(Exception):
    def __init__(self, status_code: int, error: str, message: str, details: list = None):
        self.status_code = status_code
        self.error = error
        self.message = message
        self.details = details
        self.request_id = str(uuid.uuid4())
        self.timestamp = datetime.utcnow().isoformat()

@app.exception_handler(ApiError)
async def api_error_handler(request: Request, exc: ApiError):
    response = {
        "status": exc.status_code,
        "error": exc.error,
        "message": exc.message,
        "requestId": exc.request_id,
        "timestamp": exc.timestamp
    }

    if exc.details:
        response["details"] = exc.details

    return JSONResponse(
        status_code=exc.status_code,
        content=response
    )

@app.exception_handler(Exception)
async def general_exception_handler(request: Request, exc: Exception):
    return JSONResponse(
        status_code=500,
        content={
            "status": 500,
            "error": "internal_error",
            "message": "An unexpected error occurred",
            "requestId": str(uuid.uuid4()),
            "timestamp": datetime.utcnow().isoformat()
        }
    )

function validateCreateUser(body) {
  const errors = [];

  if (!body.name || body.name.trim().length < 2) {
    errors.push({
      field: "name",
      code: "too_short",
      message: "Name must be at least 2 characters",
      value: body.name
    });
  }

  if (!body.email || !isValidEmail(body.email)) {
    errors.push({
      field: "email",
      code: "invalid_email",
      message: "A valid email address is required",
      value: body.email
    });
  }

  if (!body.password || body.password.length < 8) {
    errors.push({
      field: "password",
      code: "too_short",
      message: "Password must be at least 8 characters"
    });
  }

  return errors.length > 0 ? errors : null;
}

{
  "status": 422,
  "error": "validation_error",
  "message": "Validation failed",
  "details": [
    {
      "field": "name",
      "code": "too_short",
      "message": "Name must be at least 2 characters",
      "value": "]
    },
    {
      "field": "email",
      "code": "invalid_email",
      "message": "A valid email address is required",
      "value": "not-an-email"
    }
  ],
  "requestId": "req_xyz789",
  "timestamp": "2026-06-23T10:00:00Z"
}

function logError(error, req) {
  const logEntry = {
    requestId: error.requestId,
    timestamp: error.timestamp,
    method: req.method,
    path: req.path,
    statusCode: error.statusCode || 500,
    errorCode: error.error,
    message: error.message,
    userId: req.user?.id,
    ip: req.ip,
    userAgent: req.headers["user-agent"],
    // Stack trace in development only
    ...(Process.env.NODE_ENV === "development" && { Stack: error.Stack })
  };

  // Send to logging service
  logger.error(logEntry);

  // Send critical errors to alerting
  if (error.statusCode >= 500) {
    alertingService.sendAlert(logEntry);
  }
}