Designing Clear API Return Codes: Lessons from HTTP Status and Personalized Messages

Introduction

When a client calls an API, the response code determines whether the result meets expectations and how the payload should be processed. Many projects suffer from chaotic return‑code definitions: some use integers, others strings; some treat 0 as success, others 1 or the literal "true", leading to confusion and higher maintenance cost.

II. HTTP Status Code Reference

HTTP status codes are divided into ranges that clearly express intent. For example, 2XX (e.g., 200) means the request succeeded, while 5XX (e.g., 502) indicates a server‑side problem. By following this segmented design, developers can quickly infer the cause of an error.

III. Parameter Convention

A return code alone is insufficient; a human‑readable message must accompany it so that developers can understand the problem without consulting external documentation. Inspired by HTTP’s range segmentation, the article proposes dividing custom error codes into logical groups, as illustrated below.

With this scheme, both programs and humans can instantly differentiate API outcomes, ensuring consistency across services.

IV. Personalized Messages

While messages are primarily for engineers, different scenarios require user‑facing translations. For instance, codes 20000–29999 denote order‑creation failures:

20001 – Order creation failed because an order is already in progress.

20002 – Order creation failed because a previous order is queued.

For end‑users, these technical details should be transformed into friendly prompts such as "Sorry, you have an ongoing order; please check your order list." The API must still return the precise technical message, leaving the translation to the caller or, preferably, to the API provider.

The article suggests storing translation mappings in a database and caching them in Redis or the API server, then performing a lookup based on application_id+code before sending the response.

This approach enables distinct messages for mobile apps, WeChat mini‑programs, or web‑based enterprise portals while preserving a single source of truth for the underlying error code.

V. Unified Handling and Monitoring

With a standardized code, operators can leverage Nginx, APM tools, or custom dashboards to aggregate request counts per code, visualize distribution pie charts, and set alerts—for example, triggering an alarm when the frequency of code 99999 exceeds a threshold within a given time window.

Such metrics help quickly pinpoint systemic or business‑logic issues, turning raw error data into actionable insights.

Conclusion

A well‑designed return‑code system reduces communication friction, simplifies debugging, and lowers long‑term maintenance effort for both developers and operations teams.