Designing API Error Codes and Result Codes: Best Practices

When a client requests an API, it usually needs to use return codes to determine whether the API response meets expectations and how to handle the returned content.

Many developers have suffered from chaotic return‑code definitions: some APIs use integers, others strings; some treat 0 as success, others use 1 or "true". A thoughtful API return‑code design can lower communication and maintenance costs.

Using HTTP status codes as an example, the status codes are segmented to clearly express and distinguish meanings.

For backend developers, the commonly seen segments are:

2XX codes, e.g., 200 – request succeeded.

5XX codes, e.g., 502 – server error, indicating the service is not running properly or code execution failed.

Designing status codes in this way allows quick initial diagnosis of problems.

Beyond just a code, a corresponding message is needed so that people can understand the result.

Following the HTTP‑status‑code approach, error codes can also be segmented.

This design lets both programs and humans easily distinguish API results, emphasizing uniformity.

Usually, messages are written for engineers, but the same error may need different user‑facing messages in various scenarios. For example, codes 20001 and 20002 both indicate order‑creation failures with different internal reasons.

20001 – order creation failed, an order is already in progress.

20002 – order creation failed, the previous order is queued for creation.

For users, a friendly message like "Sorry, you have an ongoing order; please check your order list" is appropriate, while the API must return precise information. Translating messages can be handled by the caller, but providing a personalization capability at the API side is better.

These translation messages can be stored in a database and cached in Redis or on the API server.

When processing a request, the system matches and replaces the message based on application_id+code .

This allows mobile app users, WeChat mini‑program users, and web order users to see different messages.

With a unified code, we can use Nginx or APM tools to count API request code frequencies and distributions, trigger alerts based on high volumes of a specific code (e.g., 99999), and generate pie charts to discover system or business workflow issues.

In summary, a good return‑code design improves communication efficiency and reduces code maintenance costs.