Designing API Error Codes and Result Codes: Best Practices

Preface

Client applications request APIs and typically rely on return codes to determine whether the response meets expectations and how to handle the content. Many developers have suffered from inconsistent return code definitions, such as using integers or strings, or different values to indicate success, which leads to confusion.

Designing API return codes carefully is essential because a good code scheme reduces communication overhead and maintenance effort.

HTTP Status Code Reference

Taking HTTP status codes as an example, the codes are segmented to clarify their meanings. 2XX codes (e.g., 200) indicate successful requests, while 5XX codes (e.g., 502) signal server errors, helping developers quickly diagnose issues.

Parameter Convention

Only defining a numeric code is insufficient; a corresponding message is needed so that humans can understand the result.

Personalized Message

Although messages are primarily for engineers, different scenarios may require distinct user‑facing messages. For example, codes 20001 and 20002 (both in the 20000‑29999 range) represent order‑creation failures with specific reasons. Users might see a generic friendly notice, while the API returns precise technical details.

These personalized messages can be stored in a database and cached in Redis or the API host, then substituted at response time based on application_id+code .

Unified Handling of Return Information

With a unified code system, we can use Nginx or APM tools to count and visualize API request code distributions, set alerts based on the frequency of specific codes (e.g., 99999), and generate pie charts to uncover system or business issues.

In summary, a well‑designed return‑code scheme improves communication efficiency, lowers code maintenance costs, and facilitates effective monitoring and alerting for backend services.