ServerErrorV2 Class Documentation

The ServerErrorV2 class is a utility for representing server-side errors in a structured and descriptive format. It provides standardized access to error details such as failure_code and failure_message, allowing developers to understand and handle server errors effectively.

---

Purpose

The ServerErrorV2 class aims to:

• Encapsulate server error information into a manageable object.
• Provide a standardized way of accessing error codes and messages for debugging or user-facing error handling.
• Ensure consistency when dealing with API errors across the application.

---

Class Implementation

import type { Nullable } from './Nullable';

/**
 * Represents a server-side error with a unique failure code and message.
 */
export class ServerErrorV2 extends Error {
	constructor(
		private failure_code?: string, // A unique identifier for the error.
		private failure_message?: string // A descriptive message for the error.
	) {
		// Call the parent class's constructor with a formatted error message.
		super(\`[Server error] failure_code=\${failure_code} failure_message=\${failure_message}\`);

		// Ensure the proper prototype chain for extending Error.
		Object.setPrototypeOf(this, ServerErrorV2.prototype);
	}

	/**
	 * Retrieves the failure code of the error.
	 * @returns {Nullable<string>} The failure code, if available, or `null`.
	 */
	getFailureCode(): Nullable<string> {
		return this.failure_code;
	}

	/**
	 * Retrieves the failure message of the error.
	 * @returns {Nullable<string>} The failure message, if available, or `null`.
	 */
	getFailureMessage(): Nullable<string> {
		return this.failure_message;
	}
}

---

Key Properties and Methods

1. Properties

• failure_code (Optional):
  • A unique string identifier for the error.
  • Used to classify and look up specific errors programmatically.
• failure_message (Optional):
  • A human-readable message describing the error.

2. Constructor

• Accepts two optional parameters:
  • failure_code: A string representing the error code.
  • failure_message: A string providing additional error details.
• Calls the parent Error constructor to initialize the error message.
• Maintains prototype integrity with Object.setPrototypeOf.

3. Methods

• getFailureCode()
  • Returns the failure_code if available, otherwise null.
  • Use case: Developers can programmatically check for specific error codes and handle them accordingly.
• getFailureMessage()
  • Returns the failure_message if available, otherwise null.
  • Use case: Developers can log or display user-friendly error messages.

---

How failure_code is Used

1. Error Identification

The failure_code acts as a unique key to identify specific error scenarios in API responses. This allows for precise handling of errors, such as retry logic or showing tailored messages to users.

2. Programmatic Handling

Developers can use the failure_code in conditional statements or error handlers to trigger specific actions based on the error type. For example:

try {
    // API call or server interaction
} catch (error) {
    if (error instanceof ServerErrorV2) {
        switch (error.getFailureCode()) {
            case 'AUTH_001':
                // Handle authentication failure
                break;
            case 'DATA_404':
                // Handle missing data error
                break;
            default:
                // Generic error handling
        }
    }
}

---

Where to Find the Exhaustive List of failure_code Values

• API Documentation: The complete list of failure_code values is maintained in the API documentation. It includes all possible error codes returned by the server, along with their descriptions and recommended handling strategies.
• Error Specification Files: If the API team uses a shared repository or system for defining error codes (e.g., OpenAPI/Swagger specs, JSON error files, or a wiki page), you can reference it there.
  • Example Location: docs/errors/failure_codes.md in the API repository.
  • Swagger Integration: Look under the responses section of the Swagger/OpenAPI spec for the endpoint.
• Server Codebase: If you have access to the server-side code, you can find the list of error codes in the module where errors are generated or mapped.

---

Example Usage

import { ServerErrorV2 } from './ServerErrorV2';

function apiCallSimulator(): never {
	throw new ServerErrorV2('AUTH_001', 'Authentication failed: Invalid credentials');
}

try {
	apiCallSimulator();
} catch (error) {
	if (error instanceof ServerErrorV2) {
		console.error('Error Code:', error.getFailureCode());
		console.error('Error Message:', error.getFailureMessage());
	}
}

Output:

Error Code: AUTH_001
Error Message: Authentication failed: Invalid credentials