Designing Clear API Return Codes and Messages for Backend Development

When a client calls an API, developers rely on return codes to determine whether the response meets expectations and how to process the content; however, many APIs suffer from inconsistent code definitions—some use integers, others strings, and success may be indicated by 0, 1, or "true", causing confusion.

Good return‑code design reduces communication and maintenance costs. Borrowing from HTTP status codes, which are divided into ranges (e.g., 2XX for success, 5XX for server errors), helps convey meaning clearly.

Beyond the numeric code, a corresponding human‑readable message is essential. By segmenting custom error codes similarly to HTTP status codes, developers can quickly distinguish API results and maintain uniformity.

Personalized messages allow the same error code to present different texts to engineers and end‑users. For example, codes 20001 and 20002 indicate specific order‑creation failures; these can be translated into user‑friendly prompts while retaining precise technical details for debugging. Such messages can be stored in a database or cache (e.g., Redis) and retrieved by matching application_id+code at response time.

With a unified code system, tools like Nginx or APM can aggregate request counts per code, enabling statistical analysis, alerting on abnormal frequencies (e.g., a surge of code 99999), and visualizing distributions via pie charts to identify systemic issues.

In summary, a well‑designed API return‑code scheme improves communication efficiency, simplifies error tracking, and lowers overall code‑maintenance overhead.