@payello-sdk/errors

The @payello-sdk/errors package provides a comprehensive set of standardized error types designed to handle different error scenarios encountered within the Payello SDK ecosystem.

This package facilitates the process of identifying, categorizing, and handling errors in a systematic way across various operations, authentication processes, request handling, and service interactions.

This package is actively used by Payello, a financial services platform committed to advancing innovation in the financial industry. Payello champions open-source contributions, harnessing these technologies to enhance its platform and client projects.

Features

• Authentication Errors: Handle authentication-related issues, such as expired tokens, revoked access, or missing authentication credentials.
• Operation Errors: Manage errors that occur during operational processes like transaction declines, account restrictions, or compliance violations.
• Request Errors: Address errors arising from API requests, including invalid parameters, unsupported content types, or encryption requirements.
• Service Errors: Deal with errors related to service availability, dependency failures, or maintenance windows.
• API Response Generation: Create API Responses automatically from thrown errors.

Getting Started

To start using the @payello-sdk/errors package, first install it via npm:

npm install @payello-sdk/errors

or using yarn:

yarn add @payello-sdk/errors

Usage

After installation, you can import any specific error class based on the scenario you're handling. Here's an example of how to use an authentication error:

import { AuthExpiredError } from "@payello-sdk/errors"

function authenticateUser(token) {
	if (isTokenExpired(token)) {
		throw new AuthExpiredError({ expired_at: token.expire_at })
		//                           ^ hints
	}
	// Proceed with authentication
}

Similarly, you can handle different types of errors based on the operation, request, or service scenario you're dealing with.

API Response Generation

The PayelloError class extends the native Error class, adding statusCode and errorDetails properties that are pivotal for generating API response errors. Here’s a breakdown of its functionality:

• Status Code Mapping: Depending on the type of error (ErrorType), a corresponding HTTP status code is automatically defined.
• Error Details: The error details (errorDetails property) include important information about the error, such as the error type and message, which helps in diagnosing and rectifying the issue.
• Error Hints: Enhance error messages with "hints" in the errorDetails, offering users actionable suggestions, such as expected input formats or links to relevant documentation.
• toResponse: The toResponse method allows you to generate a structured response containing the error details, along with the appropriate HTTP status code. This method facilitates easy integration with web frameworks that support or require error handling through Fetch responses. You can pass a responseFactory object that implements the ResponseFactory interface to customize the response format. By default it will return a Fetch response.

API Response Example

This snippet below demonstrates how a PayelloError can be caught and how to use the generated response. The catch block checks if the error is an instance of PayelloError and uses its toResponse method to return a Fetch API response (the default).

import { InvalidBodyError, PayelloError } from '@payello-sdk/errors';

try {
    // Throw one of the errors
    throw new InvalidBodyError();
} catch (error) {
    // Check if it's a PayelloError
    if (error instanceof PayelloError) {
        // Return the generated response
        return error.toResponse();
    }
    // If not handle other types of errors or pass to a generic error handler
    console.error(error);
}

Error Categories

Authentication Errors

• AuthError
• AuthErrorCode
• AuthExpiredError
• AuthInvalidError
• AuthMissingError
• AuthRevokedError
• PermissionError
• SecurityError
• UnauthorizedIPError
• UserLockedError

Operation Errors

• OperationError
• AccountRestrictedError
• ComplianceViolationError
• DuplicateTransactionError
• FraudDetectedError
• IncompatibleError
• InsufficientResourcesError
• InvalidCurrencyError
• InvalidDetailsError
• OperationBlockedError
• QuotaError
• RateLimitError
• StateConflictError
• TransactionDeclinedError
• UnsupportedOperationError

Request Errors

• RequestError
• EncryptionRequiredError
• InvalidBodyError
• InvalidContentTypeError
• InvalidMethodError
• ParamFormatError
• ParamMissingError
• ParamTypeError
• ResourceNotFoundError

Service Errors

• ServiceError
• DependencyFailureError
• InternalError
• MaintenanceError
• ServiceUnavailableError
• TimeoutError
• UpstreamError
• UpstreamMaintenanceError
• UpstreamUnavailableError