API Response & Error Standards

Relevant source files

The following files were used as context for generating this wiki page:

• src/middlewares/error.ts
• src/middlewares/logger.ts
• comprehensive-swagger-api.json
• CLAUDE.md
• src/index.ts
• outmanage_api_tests.postman_collection.json

The Outmanage API implements a centralized and standardized approach to handling HTTP responses and application errors. This ensures that the frontend and third-party integrations receive predictable, machine-readable data structures regardless of the operation performed or the type of error encountered.

The system utilizes specialized Express middleware for global error catching and a dedicated logging service based on Winston to track system health and debug issues in real-time. Sources: src/middlewares/error.ts, CLAUDE.md:120-123

Standard Response Structure

Every successful API response follows a consistent JSON envelope. This structure allows the client to immediately determine the success of a request before parsing the payload.

Success Envelope

A successful operation returns a 2xx status code and a body with the following schema:

Field	Type	Description
success	boolean	Always true for successful requests.
data	object/array	The payload containing the requested resources or operation results.

Sources: comprehensive-swagger-api.json:52-73

Paginated Responses

For list endpoints (e.g., users, products, shipments), the data field contains an object structured for pagination:

Field	Type	Description
items	array	The list of resources for the current page.
total	integer	The total count of resources matching the query.

Sources: comprehensive-swagger-api.json:118-135

Error Handling Architecture

The project employs a centralized error handling mechanism implemented in src/middlewares/error.ts. This middleware catches all errors thrown within the application lifecycle and transforms them into standardized error responses. Sources: src/index.ts:108, src/middlewares/error.ts:114-119

Error Processing Flow

The following diagram illustrates how the system processes different types of exceptions:

The error middleware distinguishes between validation errors, custom application errors, and unexpected system failures to provide appropriate status codes. Sources: src/middlewares/error.ts:64-100

Standard Error Response Body

When an error occurs, the API returns a 4xx or 5xx status code with the following structure:

Field	Type	Description
success	boolean	Always false.
message	string	A human-readable message describing the error.
errorType	string	A machine-readable string (e.g., joiValidationError, unauthorized).
details	mixed	(Optional) Additional context, such as validation field paths.

Sources: src/middlewares/error.ts:38-46, comprehensive-swagger-api.json:74-101

Error Categories

1. Validation Errors

The system uses Joi for request validation. If a request body or query parameter fails validation, the middleware returns a 400 Bad Request. Sources: src/middlewares/error.ts:71-81

{
  "success": false,
  "message": "validation error",
  "errorType": "joiValidationError",
  "details": [
    {
      "message": "Email must be a valid email address",
      "path": ["email"],
      "type": "string.email"
    }
  ]
}

Sources: comprehensive-swagger-api.json:102-140

2. Custom Application Errors

Developers use the CustomError class to throw specific business logic errors. Sources: src/middlewares/error.ts:12-25

export class CustomError extends Error implements ICustomError {
  status: number;
  errorCode: string;
  details?: any;

  constructor(params: ErrorParams) {
    super(params.message);
    this.errorCode = params.errorCode;
    this.status = params.status || 400;
    this.details = params.details;
  }
}

Sources: src/middlewares/error.ts:12-25

3. HTTP Security Errors

The API defines standard responses for common security scenarios:

• 401 Unauthorized: Missing or invalid x-outmanage-token header.
• 403 Forbidden: User lacks necessary permissions for the resource.
• 404 Not Found: Resource UUID does not exist in the database.

Sources: comprehensive-swagger-api.json:141-175

Logging and Monitoring

The system uses Winston for structured logging. All errors processed by the error middleware are logged with detailed request context. Sources: src/middlewares/logger.ts:7-30

Logging Levels and Configuration

• Timezone: Logs use the Asia/Jakarta timezone.
• Format: JSON format is used for console output.
• Levels:
  • warn: Used for 4xx client errors.
  • error: Used for 5xx server errors and uncaught exceptions.

Sources: src/middlewares/logger.ts:11-25, src/middlewares/error.ts:90-95

Request Logging

A loggingMiddleware is applied globally to log every completed HTTP request. Sources: src/index.ts:60, src/middlewares/logger.ts:50-63

Health Check Standard

The API provides a health check endpoint at /health to verify server status and timezone configuration. Sources: src/index.ts:98-106

Property	Value	Description
status	"ok"	Indicates the service is running.
timestamp	ISO String	Current time adjusted to Jakarta (UTC+7).

Sources: src/index.ts:102-105