Designing Clear API Return Codes: Lessons from HTTP Status Codes

Preface

Clients often need to judge API results via return codes. Inconsistent designs—different data types, varied success indicators such as 0, 1, or "true"—cause headaches. Proper return‑code design reduces communication and maintenance costs.

HTTP Status Codes

HTTP status codes are segmented to clarify meaning. For backend developers, 2XX (e.g., 200 → request succeeded) and 5XX (e.g., 502 → server error) allow quick diagnosis of problems. This design philosophy can inspire API return‑code schemes.

Parameter Convention

Only a code is insufficient; a corresponding message is needed for readability.

Following HTTP’s segmentation, error codes can be grouped. Unified design lets programs and humans easily distinguish API results.

Personalized Message

Messages are usually written for engineers, but different scenarios may require user‑friendly messages. Example: codes 20000‑29999 indicate order‑creation failures; sub‑codes 20001 and 20002 describe specific reasons. Users see a generic apology, while the API returns precise details. These messages can be stored in a database and cached in Redis.

During response generation, the system matches application_id+code to replace the message, allowing mobile apps, mini‑programs, and web orders to display appropriate texts.

Unified Return Information

With a unified code, Nginx or APM tools can count and visualize code distribution, trigger alerts for abnormal spikes, and help identify system or business issues. Good return‑code design improves communication efficiency and lowers maintenance cost.