Error Handling and Codes

Relevant source files

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

• common/response.go
• common/error.go
• gateway/zalopay/payment.go
• gateway/zalopay/callback.go
• main.go
• README.md

Introduction

Error handling in the zalopay service is managed through a standardized response system defined in the common package. The system uses consistent JSON structures for both successful and failed operations, ensuring predictable responses for API clients. Errors are identified by unique integer codes, with corresponding messages centralized for easy management and retrieval.

This approach separates the error definition from its application logic. The common/error.go file acts as a central repository for all possible business logic errors, while common/response.go provides the necessary structures and helper functions to construct and send these error responses back to the client. Handlers within the gateway package utilize these common components to report issues encountered during payment processing, order status checks, or callback handling.

Core Components

The error handling mechanism is built upon two primary files: response.go for structuring the output and error.go for defining the error content.

Standard Response Structures

The service defines distinct Go structs that map directly to the JSON responses sent to clients. This ensures consistency across all endpoints.

• SuccessRes: Used for successful API calls. It contains the data payload.
• ErrorRes: Used for failed API calls. It includes a specific error code and a human-readable message.
• ZaloPayCallbackRes: A specific structure for responding to ZaloPay callbacks, which differs slightly from the general API error response.

Sources: common/response.go:5-18

The diagram below illustrates the structure of the main response types.

The ErrorRes struct is fundamental to error handling. Its fields are detailed below:

Field	Type	JSON Key	Description
ErrorCode	int	error_code	The unique integer code identifying the error.
ErrorMessage	string	error_message	A descriptive message explaining the error.

Sources: common/response.go:10-13

Centralized Error Codes

All business logic error codes and their corresponding messages are defined in a single location, common/error.go. This is achieved using a map that links integer codes to string messages.

A helper function, GetErrorMessage(code int), is provided to retrieve the message for a given code. If the code does not exist in the map, it returns an "Undefined error" message.

Sources: common/error.go:10-25

The following table lists all defined application-specific errors.

Error Code	Message	Constant Name
0	Success	Success
900	Invalid data format	ErrData
901	Invalid checksum	ErrChecksum
902	Order does not exist	ErrOrder
903	Invalid amount	ErrAmount
904	Create order failed	ErrCreate
905	Get order status failed	ErrStatus

Sources: common/error.go:5-9, common/error.go:13-21

Error Handling in Practice

API handlers in the gateway package use the common response and error modules to handle failures during request processing.

Generating Error Responses

When a handler function encounters an error, it uses response.NewErrorResponse(code int) to create and return a standardized ErrorRes object. This function retrieves the appropriate error message using error.GetErrorMessage and populates the ErrorRes struct.

The following sequence diagram shows how an error is generated and returned during a payment creation request.

ZaloPay Callback Error Handling

The ZaloPay callback endpoint has a distinct error handling flow because it must respond in a format specified by ZaloPay. When handling a callback, the system first attempts to parse the incoming data and verify its checksum. If either step fails, it uses response.NewZaloPayCallbackResponse to generate a response.

This function creates a ZaloPayCallbackRes object with a specific returncode and returnmessage. A returncode of -1 indicates failure, while 1 indicates success.

The flowchart below outlines the logic within the Callback handler.

Summary

The zalopay project employs a robust and centralized error handling strategy. By defining standard response structs in common/response.go and consolidating all error codes and messages in common/error.go, the system ensures that API clients receive consistent and predictable error information. This modular design simplifies the process of adding new errors and makes the handler logic in modules like gateway/zalopay cleaner and more maintainable.