Designing Clear API Return Codes: From HTTP Status to Custom Messages

1. Introduction

When a client requests an API, the response code is used to determine whether the result meets expectations and how to handle the returned content.

Many developers have suffered from confusing return code definitions: some APIs use integers, others strings; some treat 0 as success, others 1 or "true". Such inconsistency leads to headaches.

Designing API return codes carefully can lower communication overhead and maintenance costs.

2. HTTP Status Code Reference

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

For backend developers, the commonly seen codes are:

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

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

These status codes allow an initial diagnosis of the problem, and the design philosophy of HTTP status codes is worth borrowing.

3. Parameter Convention

Besides a numeric code, a corresponding message is needed so that humans can understand the result.

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

With such a design, both programs and humans can easily distinguish API results, and consistency is achieved.

4. Personalized Message

Typically, messages are written for engineers, but the same error may need different user‑facing messages in various scenarios.

For example, codes 20000‑29999 indicate order creation failures:

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

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

For users, a concise message like "Sorry, you have an ongoing order; please check your order list." is more appropriate.

While the API must return precise information, the user‑visible message should be translated. Providing a personalization capability on the API side is beneficial.

We can store translated messages in a database and cache them in Redis or locally on the API server.

When processing a request, we match application_id+code to replace the message accordingly.

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

5. Unified Handling of Return Information

With a unified code, we can use Nginx or APM tools to count API request codes and analyze their distribution.

By monitoring the frequency of a specific code (e.g., 99999) within a time window, we can trigger API anomaly alerts.

Code‑based pie charts help identify issues in systems and business processes.

In short, a well‑designed return code system improves communication efficiency and reduces code maintenance costs.

Link: https://ken.io/note/api-errorcode-or-resultcode-desgin