Skip to main content
Version: 0.5.0 (Previous)

🚨 Error Handling

Proper error handling is crucial for building robust backend services. The Nodeblocks SDK provides comprehensive error handling patterns that ensure consistent, user-friendly error responses across all services.

🎯 Error Response Format​

All Nodeblocks services return errors in a consistent JSON format:

{
  "error": {
    "message": "Error message description",
    "data": ["Additional error details"]
  }
}

Validation Errors​

When request validation fails, additional details are included:

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must have required property 'name'",
      "request body must have required property 'email'",
      "request body must NOT have additional properties"
    ]
  }
}

📋 Common Error Codes​

400 Bad Request​

  • Validation Error - Invalid request body format or missing required fields
  • Failed to create [entity] - Database insert operation failed to return an inserted ID
  • Failed to update [entity] - Update operation doesn't modify any data (no changes detected)
  • Failed to delete [entity] - Database deletion operation failed

401 Unauthorized​

  • token could not be verified - Missing or invalid authorization token
  • Authentication failed - Missing or invalid authentication token
  • Token fails security check - Token security validation failed

403 Forbidden​

  • User is not authorized to access this resource - User lacks required permissions
  • User is not authorized to access this [entity] - User lacks specific entity permissions

404 Not Found​

  • [Entity] not found - Entity doesn't exist for the requested operation
  • [Entity] does not exist - Entity doesn't exist for the requested operation

409 Conflict​

  • [Entity] already exists - Entity with the same identifier already exists
  • User with this email already exists - Duplicate user email

500 Internal Server Error​

  • Failed to create [entity] - Database connection issues or unexpected failures during creation
  • Failed to get [entity] - Database connection issues or unexpected failures during retrieval
  • Failed to find [entities] - Database connection issues, invalid filter syntax, or unexpected failures during listing
  • Failed to update [entity] - Database connection issues or unexpected failures during update
  • Failed to delete [entity] - Database connection issues or unexpected failures during deletion

🔧 Service-Specific Error Patterns​

Authentication Service Errors​

{
  "error": {
    "message": "token could not be verified"
  }
}
{
  "error": {
    "message": "Authentication failed"
  }
}

User Service Errors​

{
  "error": {
    "message": "User profile not found"
  }
}
{
  "error": {
    "message": "Identity is not authorized to access this resource"
  }
}

Organization Service Errors​

{
  "error": {
    "message": "Organization not found"
  }
}
{
  "error": {
    "message": "Failed to create organization"
  }
}

Product Service Errors​

{
  "error": {
    "message": "Product not found"
  }
}
{
  "error": {
    "message": "Failed to create product"
  }
}

Category Service Errors​

{
  "error": {
    "message": "Category does not exist"
  }
}
{
  "error": {
    "message": "Failed to create category"
  }
}

Attribute Service Errors​

{
  "error": {
    "message": "Attribute group not found"
  }
}
{
  "error": {
    "message": "Failed to create attribute group"
  }
}

Order Service Errors​

{
  "error": {
    "message": "Order not found"
  }
}
{
  "error": {
    "message": "Failed to create order"
  }
}

Chat Service Errors​

{
  "error": {
    "message": "Channel not found"
  }
}
{
  "error": {
    "message": "Chat message not found"
  }
}

📐️ Error Handling Best Practices​

1. Consistent Error Messages​

Use consistent, user-friendly error messages across all services:

// ✅ Good: Clear, actionable error messages
"User profile not found"
"Failed to create organization"
"Validation Error"

// ❌ Avoid: Technical or unclear messages
"Database connection failed"
"Internal server error"
"Something went wrong"

2. Proper HTTP Status Codes​

Use appropriate HTTP status codes for different error types:

  • 400 - Bad Request (validation errors, missing fields)
  • 401 - Unauthorized (authentication failures)
  • 403 - Forbidden (authorization failures)
  • 404 - Not Found (entity doesn't exist)
  • 409 - Conflict (duplicate entities)
  • 500 - Internal Server Error (database issues, unexpected failures)

3. Validation Error Details​

Include specific validation error details in the data array:

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must have required property 'name'",
      "request body must have required property 'email'",
      "request body must NOT have additional properties"
    ]
  }
}

4. Authentication Error Handling​

Always check for authentication errors first:

// Check authentication before processing
if (!isAuthenticated(request)) {
  return {
    status: 401,
    body: {
      error: {
        message: "token could not be verified"
      }
    }
  };
}

5. Authorization Error Handling​

Check user permissions for protected operations:

// Check authorization for admin-only operations
if (!hasAdminRole(user)) {
  return {
    status: 403,
    body: {
      error: {
        message: "User is not authorized to access this resource"
      }
    }
  };
}

⚙️ Error Middleware Setup​

To ensure consistent error handling across your application, use the nodeBlocksErrorMiddleware:

import express from 'express';
import { MongoClient } from 'mongodb';
import { middlewares, services } from '@nodeblocks/backend-sdk';

const { nodeBlocksErrorMiddleware } = middlewares;
const { userService, organizationService } = services;

const client = new MongoClient('mongodb://localhost:27017').db('dev');

express()
  .use(userService({
    users: client.collection('users'),
    identity: client.collection('identity')
  }))
  .use(organizationService({
    organizations: client.collection('organizations'),
    identity: client.collection('identity')
  }))
  .use(nodeBlocksErrorMiddleware()) // Must be last
  .listen(8089, () => console.log('Server running'));

⚠️ Important: Always add nodeBlocksErrorMiddleware() after your routes and services to ensure all errors are properly formatted as JSON responses.

🔍 Error Debugging​

Development Mode​

In development mode, additional error details may be included:

{
  "error": {
    "message": "Database connection failed",
    "stack": "Error: Database connection failed\n    at createUser...",
    "data": {
      "operation": "createUser",
      "timestamp": "2024-05-28T09:41:22.552Z"
    }
  }
}

Production Mode​

In production, only essential error information is returned:

{
  "error": {
    "message": "Internal server error"
  }
}

📝 Error Logging​

Structured Logging​

Log errors with structured data for better debugging:

const logError = (error: any, context: any) => {
  console.error('API Error:', {
    message: error.message,
    status: error.status,
    timestamp: new Date().toISOString(),
    endpoint: context.endpoint,
    userId: context.userId,
    requestId: context.requestId
  });
};

Error Monitoring​

Consider integrating with error monitoring services:

// Example with error monitoring service
const handleError = (error: any, req: any, res: any) => {
  // Log to monitoring service
  errorMonitoringService.captureException(error, {
    extra: {
      endpoint: req.path,
      method: req.method,
      userId: req.user?.id
    }
  });
  
  // Return user-friendly response
  res.status(error.status || 500).json({
    error: {
      message: error.message || 'Internal server error'
    }
  });
};