Skip to main content

​
What is StatusFlow?

StatusFlow is a lightweight, powerful SDK for Node.js and Express that simplifies HTTP error handling and response management. It provides standardized, bilingual (English/Spanish) HTTP responses with rich metadata, making it easy to build consistent, user-friendly APIs. Instead of manually crafting error responses or managing status codes across your application, StatusFlow gives you:
  • Bilingual responses - Built-in English and Spanish support for all HTTP status codes
  • Rich error context - Automatic inclusion of error names, categories, descriptions, and possible causes
  • Two flexible approaches - Use exception-based error handling or functional responses
  • Type safety - Full TypeScript support with comprehensive type definitions
  • Express integration - Drop-in middleware for seamless Express.js integration

​
Key Features

Bilingual Support

All HTTP status codes include both English and Spanish messages, descriptions, and context.

Exception Classes

Pre-built exception classes for common HTTP errors (BadRequestException, NotFoundException, etc.).

StatusFlow Function

Functional approach to generate status responses with custom messages and extra data.

Express Middleware

Ready-to-use middleware for automatic error handling in Express applications.

​
Why Use StatusFlow?

​
Consistency Across Your API

Without StatusFlow, your error responses might look like this: 
// Inconsistent error handling
app.get('/user/:id', (req, res) => {
  if (!user) {
    return res.status(404).json({ error: 'User not found' }); // Different format
  }
});

app.post('/user', (req, res) => {
  if (!valid) {
    return res.status(400).send('Invalid data'); // Another format
  }
});
With StatusFlow, all responses follow a consistent structure: 
import { StatusFlow, StatusFlowCodes } from 'status-flow';

app.get('/user/:id', (req, res) => {
  if (!user) {
    return res.status(404).json(
      StatusFlow({ 
        code: StatusFlowCodes.NOT_FOUND,
        lang: 'en',
        overrideMessage: 'User not found'
      })
    );
  }
});

​
Rich Error Context

Every StatusFlow response includes comprehensive metadata: 
{
  "success": false,
  "message": "User not found",
  "code": 404,
  "info": {
    "name": "Not Found",
    "category": "Client Error",
    "description": "The requested resource could not be found.",
    "possibleCauses": [
      "Resource does not exist",
      "Incorrect URL or identifier"
    ]
  }
}

​
Bilingual by Default

Switch between languages effortlessly: 
// English response
StatusFlow({ code: 404, lang: 'en' });

// Spanish response (default)
StatusFlow({ code: 404, lang: 'es' });
The language can be automatically detected from request headers using the included middleware: 
const lang = req.headers['x-lang'] === 'en' ? 'en' : 'es';

​
Use Cases

StatusFlow is perfect for:
  • REST APIs - Standardize error responses across all endpoints
  • Microservices - Ensure consistent error handling across services
  • Bilingual applications - Serve users in multiple languages without extra code
  • API documentation - Provide rich error context for client developers
  • International teams - Support Spanish and English speaking developers

​
Two Approaches to Error Handling

StatusFlow supports two different patterns based on your preference:

​
1. Exception-Based (Traditional)

import { NotFoundException, httpErrorMiddleware } from 'status-flow';

app.get('/user/:id', (req, res, next) => {
  const user = findUser(req.params.id);
  if (!user) {
    throw new NotFoundException('User not found');
  }
  res.json(user);
});

app.use(httpErrorMiddleware);

​
2. Functional (StatusFlow)

import { StatusFlow, StatusFlowCodes, statusFlowMiddleware } from 'status-flow';

app.get('/user/:id', (req, res) => {
  const user = findUser(req.params.id);
  if (!user) {
    return res.status(404).json(
      StatusFlow({ code: StatusFlowCodes.NOT_FOUND })
    );
  }
  res.json(StatusFlow({ 
    code: StatusFlowCodes.OK,
    extra: { user }
  }));
});

app.use(statusFlowMiddleware);

​
Next Steps

Installation

Install StatusFlow and set up your project

Quick Start

Build your first API with StatusFlow in minutes

Build docs developers (and LLMs) love

Get started for freeTalk to us